Csak a szükséges eseményekre iratkozzon fel
Hozzon létre egy végpontot aPOST /v3/webhooks művelettel. Csak olyan dokumentált eseményekre iratkozzon fel, amelyek meghajtják az integrációját. Ez a példa a transfer.state_changed eseményt használja.
Create webhook endpoint
data.id értékét WEBHOOK_ID-ként. Kérjen portál URL-t a GET /v3/webhooks/portal végponttól egy webhooks:write jogosultsággal rendelkező API-kulccsal, kérje le ennek a végpontnak az aláíró titkát, és tárolja külön az API-kulcstól egy titkos kulcskezelőben. A portál URL önmagában hozzáférést biztosít, és egy óra után lejár, ezért minden alkalommal kérjen újat, és ne tárolja vagy ossza meg.
A portál erőforrás szerint csoportosítja a v3 eseményeket: Customers, Capabilities, Accounts, Recipients, Transfers és API. Minden eseménynél megjelenik a payload sémája és egy példa. A régi (legacy) események elavultként vannak megjelölve, és egy külön Legacy csoportban szerepelnek. Ha a végpontja már feliratkozott egy régi eseményre, továbbra is megkapja azt. Új feliratkozásokhoz v3 eseményneveket válasszon.
Egy végpont eseményeinek módosítása
Egy végpontot aGET /v3/webhooks/{webhookId} művelettel olvashat be. A válasz events szerkezete megegyezik a GET /v3/webhooks válaszáéval. Soha nem tartalmazza az aláíró titkot. Az olvasáshoz webhooks:read jogosultság szükséges, ismeretlen végpontazonosító esetén pedig 404 not_found a válasz.
A végpontot a PATCH /v3/webhooks/{webhookId} művelettel frissítheti. Küldjön Idempotency-Key fejlécet. A frissítéshez webhooks:write jogosultság szükséges.
- Csak az
eventsmezőt küldje, ha meg szeretné tartani az aktuális URL-t. - Csak az
urlmezőt küldje, ha meg szeretné tartani az aktuális eseménykiválasztást. - Az
eventsa teljes kiválasztást lecseréli. Először olvassa be a végpontot, és adjon meg minden eseményt, amelyre még szüksége van. - Az új feliratkozásoknak v3 eseményneveket kell használniuk.
- Megtarthat egy régi eseménynevet, ha a végpont már feliratkozott rá. Új régi eseménynév hozzáadása
400 validation_errorhibát ad vissza.
Request body
Ellenőrzés az elemzés előtt
A Swipelux az új webhook integrációkat Svix-en keresztül szállítja. Ellenőrizze a nyers kéréstörzset a végpont aláíró titkával és ezekkel a fejlécekkel:svix-idsvix-timestampsvix-signature
Verify signature
Tárolás, nyugtázás, majd feldolgozás
Tegyen egyediségi kényszert a borítékid mezőjére. Tárolja az ellenőrzött borítékot, gyorsan adjon vissza 2xx-et, majd dolgozza fel aszinkron módon.
Ha az esemény ID már létezik, nyugtázza a kézbesítést anélkül, hogy megismételné a befejezett mellékhatásokat. A függőben lévő vagy sikertelen helyi munkát a saját újrapróbáló során keresztül folytassa. Ne használja a boríték attempt mezőjét deduplikációs kulcsként vagy szállítási újrapróbálási számlálóként.
Aktuális állapot újbóli lekérése
A webhook-sorrend nem hiteles erőforrás-előzmény. Használja aresource.type és resource.id értékeket az objektum megtalálásához, majd kérje le az aktuális állapotát, mielőtt frissíti a rendszerét.
Átutalás eseményhez hívja a GET /v3/transfers/{transferId} műveletet:
Refetch transfer
Kézbesítések helyreállítása
Használja aGET /v3/webhooks/portal műveletet a kézbesítési naplók megnyitásához. webhooks:write jogosultsággal a sikertelen kézbesítéseket is újrapróbálhatja, vagy manuális újrajátszást indíthat. A csak webhooks:read jogosultsággal rendelkező kulcs olyan portált nyit meg, amely megjeleníti a kézbesítéseket, de nem tudja újrapróbálni vagy újrajátszani őket, és nem fedi fel az aláíró titkokat.
Minden újrajátszásnak ugyanazon az aláírás-ellenőrzésen és tartós inboxon kell átmennie. Leállás utáni helyreállításhoz játssza le az érintett időablakot és kérje le újra minden hivatkozott erőforrást. A befejezett esemény ID-k no-op-ok maradnak; a befejezetlen rekordok aszinkron folytatódnak.
Ezután ellenőrizze a duplikált és nem sorrendben érkező kézbesítéseket sandboxban, majd fejezze be az Éles indulás ellenőrzőlistát.