Skip to main content
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.
Tallenna vastauksen data.id muuttujaan WEBHOOK_ID. Avaa GET /v3/webhooks/portal -toiminnon palauttama portaali, hae tämän päätepisteen allekirjoitussalaisuus ja tallenna se erillään API-avaimestasi salaisuudenhallintaan.

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.
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}:
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, uudelleenyrittääksesi epäonnistuneet toimitukset tai aloittaaksesi manuaalisen toiston. 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.