Ugrás a fő tartalomhoz
Használjon webhookokat az aszinkron változásokra való reagáláshoz. A kézbesítés legalább egyszer történik, ezért a duplikált, késleltetett és nem sorrendben érkező események normálisak.

Csak a szükséges eseményekre iratkozzon fel

Hozzon létre egy végpontot a POST /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
Tárolja a válasz 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 a GET /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 events mezőt küldje, ha meg szeretné tartani az aktuális URL-t.
  • Csak az url mezőt küldje, ha meg szeretné tartani az aktuális eseménykiválasztást.
  • Az events a 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_error hibát ad vissza.
Ez a törzs megtartja az URL-t, és lecseréli a kiválasztást:
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-id
  • svix-timestamp
  • svix-signature
Az ellenőrzés sikeres befejezése előtt ne elemezzen JSON-t és ne okozzon mellékhatásokat.
Verify signature
Utasítsa el a hiányzó vagy érvénytelen aláírásokkal érkező kéréseket. Tartsa elérhetőnek a nyers törzset, amíg az ellenőrzés be nem fejeződik.

Tárolás, nyugtázás, majd feldolgozás

Tegyen egyediségi kényszert a boríték id 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 a resource.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
Az ügyfélnek látható státuszt és a downstream műveleteket az aktuális API válaszból vezérelje. A mellékhatásokat úgy tervezze, hogy biztonságosak maradjanak, ha két worker eltérő sorrendben dolgozza fel a kapcsolódó eseményeket.

Kézbesítések helyreállítása

Használja a GET /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.