Přejít na hlavní obsah
Webhooky používejte k reakci na asynchronní změny. Doručení je alespoň jednou, takže duplicitní, zpožděné a mimo pořadí příchozí události jsou běžné.

Registrujte pouze potřebné události

Vytvořte endpoint pomocí POST /v3/webhooks. Odebírejte pouze zdokumentované události, které řídí vaši integraci. Tento příklad používá transfer.state_changed.
Create webhook endpoint
Uložte data.id z odpovědi jako WEBHOOK_ID. S API klíčem, který má webhooks:write, si vyžádejte URL portálu z GET /v3/webhooks/portal, získejte podpisové tajemství tohoto endpointu a uložte jej odděleně od API klíče v secret manageru. URL portálu sama o sobě uděluje přístup a její platnost vyprší po jedné hodině, proto si pokaždé vyžádejte novou a neukládejte ji ani ji nesdílejte. Portál seskupuje události v3 podle zdroje: Customers, Capabilities, Accounts, Recipients, Transfers a API. U každé události je zobrazeno schéma payloadu a příklad. Starší (legacy) události jsou označeny jako zastaralé a uvedeny v samostatné skupině Legacy. Pokud je váš endpoint k legacy události již přihlášen, bude ji nadále dostávat. Pro nová přihlášení volte názvy událostí v3.

Změňte události endpointu

Jeden endpoint načtete pomocí GET /v3/webhooks/{webhookId}. Odpověď má stejný tvar events jako GET /v3/webhooks. Nikdy neobsahuje podpisové tajemství. Čtení vyžaduje webhooks:read a pro neznámé ID endpointu vrací 404 not_found. Endpoint aktualizujte pomocí PATCH /v3/webhooks/{webhookId}. Odešlete hlavičku Idempotency-Key. Aktualizace vyžadují webhooks:write.
  • Odešlete pouze events, chcete-li zachovat aktuální URL.
  • Odešlete pouze url, chcete-li zachovat aktuální výběr událostí.
  • events nahrazuje celý výběr. Nejprve endpoint načtěte a uveďte každou událost, kterou stále potřebujete.
  • Nová přihlášení musí používat názvy událostí v3.
  • Název legacy události si můžete ponechat, pokud je k ní endpoint již přihlášen. Přidání nového legacy názvu vrátí 400 validation_error.
Toto tělo zachová URL a nahradí výběr:
Request body

Ověřte před parsováním

Swipelux doručuje nové webhookové integrace přes Svix. Ověřte surové tělo požadavku pomocí podpisového tajemství vašeho endpointu a těchto hlaviček:
  • svix-id
  • svix-timestamp
  • svix-signature
Neparsujte JSON ani nezpůsobujte vedlejší efekty, dokud ověření neuspěje.
Verify signature
Odmítejte požadavky s chybějícím nebo neplatným podpisem. Surové tělo mějte k dispozici, dokud ověření nedokončí.

Uložte, potvrďte a poté zpracujte

Zaveďte omezení unikátnosti na id obálky. Uložte ověřenou obálku, rychle vraťte 2xx a poté ji zpracujte asynchronně. Pokud ID události již existuje, potvrďte doručení bez opakování dokončených vedlejších efektů. Rozpracovanou nebo neúspěšnou lokální práci obnovte přes vlastní frontu pro opakování. Nepoužívejte pole attempt obálky jako deduplikační klíč ani jako čítač transportních opakování.

Znovu načtěte aktuální stav

Pořadí webhooků není autoritativní historií zdroje. Pomocí resource.type a resource.id najděte objekt a poté před aktualizací vašeho systému načtěte jeho aktuální stav. Pro událost převodu volejte GET /v3/transfers/{transferId}:
Refetch transfer
Stav viditelný zákazníkovi a navazující akce odvozujte z aktuální API odpovědi. Vedlejší efekty navrhujte tak, aby zůstaly bezpečné, i když dva pracovníci zpracují související události v jiném pořadí.

Obnovte doručení

Použijte GET /v3/webhooks/portal k otevření logů doručení. S webhooks:write můžete také opakovat neúspěšná doručení nebo spustit manuální přehrání. Klíč pouze s webhooks:read otevře portál, který zobrazuje doručení, ale nemůže je opakovat, znovu přehrát ani odhalit podpisová tajemství. Každé přehrání musí projít stejným ověřením podpisu a trvanlivou schránkou. Pro obnovu po výpadku přehrajte dotčené okno a znovu načtěte každý odkazovaný zdroj. Dokončená ID událostí zůstávají bez efektu; nedokončené záznamy pokračují asynchronně. Dále v sandboxu ověřte duplicitní a mimo pořadí doručené doručení, poté dokončete kontrolní seznam Uvedení do provozu.