Siirry pääsisältöön
Käytä webhookkeja reagoidaksesi asynkronisiin muutoksiin. Toimitus on vähintään kerran, joten päällekkäiset, viivästyneet ja epäjärjestyksessä olevat tapahtumat ovat normaaleja.

Rekisteröi vain tarvitsemasi tapahtumat

Luo päätepiste POST /v3/webhooks -toiminnolla. Tilaa vain dokumentoituja tapahtumia, jotka ohjaavat integraatiotasi. Tämä esimerkki käyttää transfer.state_changed -tapahtumaa.
Create webhook endpoint
Tallenna vastauksen data.id muuttujaan WEBHOOK_ID. Pyydä portaalin URL GET /v3/webhooks/portal -toiminnolta API-avaimella, jolla on oikeus webhooks:write, hae tämän päätepisteen allekirjoitussalaisuus ja tallenna se erillään API-avaimestasi salaisuudenhallintaan. Portaalin URL antaa pääsyn sellaisenaan ja vanhenee tunnin kuluttua, joten pyydä uusi joka kerta äläkä tallenna tai jaa sitä. Portaali ryhmittelee v3-tapahtumat resurssin mukaan: Customers, Capabilities, Accounts, Recipients, Transfers ja API. Jokaisesta tapahtumasta näytetään sen payload-skeema ja esimerkki. Vanhat tapahtumat merkitään vanhentuneiksi ja listataan erilliseen Legacy-ryhmään. Jos päätepisteesi on jo tilannut vanhan tapahtuman, se saa sitä edelleen. Valitse uusiin tilauksiin v3-tapahtumanimet.

Muuta päätepisteen tapahtumia

Lue yksittäinen päätepiste GET /v3/webhooks/{webhookId} -toiminnolla. Vastauksessa on sama events-rakenne kuin GET /v3/webhooks -toiminnossa. Se ei koskaan sisällä allekirjoitussalaisuutta. Lukeminen vaatii webhooks:read-oikeuden ja palauttaa 404 not_found -virheen tuntemattomalle päätepisteen ID:lle. Päivitä päätepiste PATCH /v3/webhooks/{webhookId} -toiminnolla. Lähetä Idempotency-Key-otsake. Päivitykset vaativat webhooks:write-oikeuden.
  • Lähetä vain events, jos haluat säilyttää nykyisen URL-osoitteen.
  • Lähetä vain url, jos haluat säilyttää nykyisen tapahtumavalinnan.
  • events korvaa koko valinnan. Lue päätepiste ensin ja sisällytä jokainen tapahtuma, jota vielä tarvitset.
  • Uusien tilausten on käytettävä v3-tapahtumanimiä.
  • Voit säilyttää vanhan tapahtumanimen, jos päätepiste on jo tilannut sen. Uuden vanhan nimen lisääminen palauttaa 400 validation_error -virheen.
Tämä runko säilyttää URL-osoitteen ja korvaa valinnan:
Request body

Vahvista ennen jäsennystä

Swipelux toimittaa uudet webhook-integraatiot Svixin kautta. Vahvista raaka pyyntörunko päätepisteesi allekirjoitussalaisuudella ja näillä otsakkeilla:
  • svix-id
  • svix-timestamp
  • svix-signature
Älä jäsennä JSON:ää tai aiheuta sivuvaikutuksia ennen kuin vahvistus onnistuu.
Verify signature
Hylkää pyynnöt, joissa on puuttuva tai virheellinen allekirjoitus. Pidä raaka runko saatavilla, kunnes vahvistus valmistuu.

Tallenna, kuittaa, sitten käsittele

Aseta yksilöllisyysrajoite kirjekuoren id-kentälle. Tallenna vahvistettu kirjekuori, palauta 2xx nopeasti, käsittele se sitten asynkronisesti. Jos tapahtuman ID on jo olemassa, kuittaa toimitus toistamatta valmiita sivuvaikutuksia. Jatka odottavaa tai epäonnistunutta paikallista työtä oman uudelleenyritysjonosi kautta. Älä käytä kirjekuoren attempt-kenttää deduplikointiavaimena tai kuljetuksen uudelleenyrityslaskurina.

Hae nykyinen tila uudelleen

Webhookin järjestys ei ole arvovaltainen resurssihistoria. Käytä resource.type- ja resource.id-arvoja objektin paikantamiseen, hae sitten sen nykyinen tila ennen järjestelmäsi päivittämistä. Siirtotapahtumassa kutsu GET /v3/transfers/{transferId}:
Refetch transfer
Aja asiakkaalle näkyvä tila ja alavirran toimet nykyisestä API-vastauksesta. Suunnittele sivuvaikutukset pysymään turvallisina, jos kaksi työntekijää käsittelee toisiinsa liittyviä tapahtumia eri järjestyksessä.

Palauta toimitukset

Käytä GET /v3/webhooks/portal -toimintoa avataksesi toimituslokit. Oikeudella webhooks:write voit myös uudelleenyrittää epäonnistuneet toimitukset tai aloittaa manuaalisen toiston. Avain, jolla on vain oikeus webhooks:read, avaa portaalin, joka näyttää toimitukset mutta ei voi uudelleenyrittää tai toistaa niitä eikä paljastaa allekirjoitussalaisuuksia. Jokaisen toiston täytyy kulkea saman allekirjoitusvahvistuksen ja kestävän saapumislaatikon läpi. Toipuaksesi katkoksen jälkeen toista vaikuttava ikkuna ja hae kukin viitattu resurssi uudelleen. Valmiit tapahtuma-ID:t pysyvät tekemättöminä; keskeneräiset tietueet jatkuvat asynkronisesti. Seuraavaksi vahvista päällekkäiset ja epäjärjestyksessä olevat toimitukset sandboxissa, suorita sitten Käynnistys tuotantoon -tarkistuslista.