Mitä seurannan webhook-päätepisteen tulisi palauttaa? Tilakoodit, aikakatkaisut ja uudelleenyritykset?
Seuranta-webhook-päätepisteen tulisi palauttaa nopea ja tarkoituksellinen 2xx-vastaus sen jälkeen, kun se on hyväksynyt tapahtuman käsiteltäväksi. Useimmissa integraatioissa turvallisin toimintamalli on todentaa pyyntö, validoida hyötykuorma, tallentaa tapahtuma tai lisätä se jonoon ja kuitata se vastauksella 200 OK tai 202 Accepted. Käytä 4xx-vastauksia pyynnöille, joita lähettäjän ei pitäisi yrittää uudelleen, ja 5xx-vastauksia, kun tilapäinen palvelinpuolen ongelma esti hyväksymisen. Tarkka aikakatkaisu- ja uudelleenyrityskäyttäytyminen riippuu edelleen webhook-palveluntarjoajan sopimuksesta, joten toteutus tulisi suunnitella dokumentoidun lähettäjän toiminnan, ei oletusten, perusteella.
Seuranta- tai toimitustila-webhookin tapauksessa tällä erolla on merkitystä, koska toimitustapahtumat voivat saapua useammin kuin kerran, väärässä järjestyksessä tai uudelleen toistettuina verkkovirheen jälkeen. Päätepisteen tehtävänä ei välttämättä ole suorittaa jokaista liiketoimintatoimintoa loppuun ennen vastaamista. Sen ensisijainen tehtävä on tehdä luotettava päätös siitä, onko tapahtuma hyväksytty.
Vastaussopimus käytännössä
Webhook-vastauksella on kaksi yleisöä: lähettävä järjestelmä ja oma sovelluksesi. Lähettäjä tarvitsee selkeän HTTP-tuloksen voidakseen päättää, merkitäänkö toimitus onnistuneeksi, yritetäänkö sitä uudelleen vai lopetetaanko yritykset. Sovelluksesi tarvitsee riittävästi aikaa tapahtuman tarkistamiseen ja pysyvään tallentamiseen. Nämä tavoitteet on helpompi saavuttaa, kun päätepisteellä on lyhyt synkroninen polku ja erillinen asynkroninen käsittelypolku.
- Vastaanota HTTP-pyyntö HTTPS:n kautta.
- Tarkista allekirjoitus, tunnistetiedot, aikaleima tai muut palveluntarjoajan edellyttämät pyynnön eheyden varmistukset.
- Jäsennä ja validoi hyötykuorma suorittamatta hitaita jatkokäsittelytoimia.
- Kirjoita tapahtuma tai deduplikointitietue ja tapahtumaviite pysyvään tallennukseen tai luotettavaan jonoon.
- Palauta tarkoituksellinen 2xx-vastaus.
- Käsittele seurannan päivitys, asiakasilmoitus, varastomuutos tai muu liiketoimintatoiminto asynkronisesti.
Vastauksessa ei pitäisi ilmoittaa hyväksymisestä, jos tapahtuma on olemassa vain prosessin muistissa. Jos sovellus kaatuu heti onnistumisesta ilmoittamisen jälkeen, tapahtuma, jota ei koskaan tallennettu pysyvästi, voi kadota lähettäjän uskoessa toimituksen onnistuneen. Sen vuoksi hetken, jolloin palautat 2xx-vastauksen, on vastattava todellista pysyvyyden takaasi.
Minkä tilakoodin webhookin pitäisi palauttaa?
| Vastaus | Merkitys lähettäjälle | Tyypillinen webhook-käyttö |
|---|---|---|
200 OK | Pyyntö hyväksyttiin ja käsiteltiin onnistuneesti. | Käytännöllinen oletus validoinnin ja pysyvän hyväksymisen jälkeen. |
202 Accepted | Pyyntö hyväksyttiin käsiteltäväksi, mutta työ voi jatkua. | Hyödyllinen, kun tapahtuma on lisätty turvallisesti jonoon mutta liiketoimintakäsittely tapahtuu asynkronisesti. |
204 No Content | Pyyntö onnistui eikä vastaussisältöä tarvita. | Sopii, kun palveluntarjoaja hyväksyy tyhjän onnistumisvastauksen. |
400–499 | Pyyntö on virheellinen, luvaton tai sellaisenaan hyväksymätön. | Virheellinen hyötykuorma, epäonnistunut todennus, virheellinen allekirjoitus tai pysyvästi hylätty tapahtuma. |
429 Too Many Requests | Vastaanottaja soveltaa nopeusrajoitusta. | Käytä vain, kun lähettäjän uudelleenyrityskäyttäytyminen ja nopeusrajoituskäytäntösi ovat yhteensopivia. |
500–599 | Vastaanottaja ei voinut hyväksyä pyyntöä palvelinpuolen tai tilapäisen ongelman vuoksi. | Tietokantakatkos, jonon virhe, riippuvuuden toimintahäiriö tai odottamaton sovellusvirhe. |
200 OK on usein vähiten yllättävä valinta, koska se ymmärretään laajasti onnistuneeksi vastaanotoksi. 202 Accepted on myös semanttisesti hyödyllinen, kun päätepiste on hyväksynyt tapahtuman myöhempää käsittelyä varten. Kumpikaan koodi ei ole automaattisesti oikea: lähettäjän dokumentaatio voi määrittää, mitkä 2xx-vastaukset lasketaan onnistuneiksi, ja jotkin palveluntarjoajat voivat edellyttää tiettyä sisältöä tai sisältötyyppiä.
Älä palauta 2xx-vastausta vain siksi, että HTTP-pyyntö saavutti palvelimesi. Jos allekirjoituksen tarkistus epäonnistuu tai hyötykuormaa ei voida tulkita turvallisesti, 4xx-vastaus on yleensä totuudenmukaisempi. Älä kuitenkaan palauta 4xx-vastausta tilapäisen tietokantakatkoksen vuoksi, jos tapahtuma voisi onnistua myöhemmin. 5xx-vastaus antaa uudelleenyrityksiä tukevalla lähettäjälle mahdollisuuden toimittaa tapahtuma uudelleen, vaikka palveluntarjoaja voi soveltaa omaa käytäntöään.
Miten aikakatkaisuja pitäisi käsitellä?
Webhookien aikakatkaisuarvot ovat palveluntarjoajakohtaisia. Ei ole olemassa yleistä HTTP-aikakatkaisua, jota kaikki seurantapalvelut käyttäisivät, ja lähettäjä voi lopettaa odottamisen ennen kuin sovelluksesi saa hitaan toiminnon päätökseen. Käsittele lähettäjän dokumentoitua aikakatkaisua enimmäisrajana, ei tavoitteena. Päätepisteesi pitäisi normaalisti vastata hyvissä ajoin ennen tätä rajaa.
Yleisin suunnitteluvirhe on kaiken jatkokäsittelyn suorittaminen ennen webhookin kuittaamista. Käsittelijä voi kutsua peräkkäin tietokantaa, tilaustenhallintajärjestelmää, ilmoituspalvelua ja analytiikkaputkea. Yksi hidas riippuvuus voi aiheuttaa lähettäjälle aikakatkaisun, vaikka sovelluksesi lopulta suorittaisi työn loppuun. Lähettäjä voi silloin yrittää uudelleen, mikä aiheuttaa kaksoiskäsittelyä tai keskenään kilpailevia päivityksiä.
Pidä synkroninen polku rajattuna työhön, jota tarvitaan turvallisen hyväksymispäätöksen tekemiseen. Siihen kuuluvat yleensä pyynnön todentaminen, perustason skeemavalidointi, tapahtuman pysyvä tallennus ja jonoon julkaiseminen. Siirrä kallis rikastaminen, kuljetusyhtiöhaut, asiakasviestit ja kolmansien osapuolten API-kutsut työntekijän käsiteltäviksi. Seuraa erikseen tapahtuman vastaanottamiseen, validointiin, pysyvään tallentamiseen ja kuittaamiseen kuluvaa aikaa sekä sen käsittelyyn kuluvaa aikaa.
Aikakatkaisu ei ole sama asia kuin epäonnistunut liiketoimintatoiminto. Lähettäjän näkökulmasta aikakatkaisu tarkoittaa yleensä, ettei se saanut käyttökelpoista onnistumisvastausta. Palvelusi on voinut tallentaa tapahtuman onnistuneesti juuri ennen yhteyden sulkeutumista. Siksi idempotenssi ja deduplikointi ovat tarpeen, vaikka päätepiste vaikuttaisi luotettavalta.
Mikä aiheuttaa uudelleenyrityksiä?
Webhookin lähettäjä voi yrittää uudelleen yhteysvirheen, aikakatkaisun tai sellaisen vastauksen jälkeen, jonka sopimus luokittelee epäonnistuneeksi. Tarkka aikataulu, yritysten enimmäismäärä, backoff-algoritmi ja toimitusikkuna vaihtelevat palveluntarjoajittain. Älä lupaa kiinteää uudelleenyritysten määrää, ellei sitä ole ilmoitettu palveluntarjoajan dokumentaatiossa.
Vastaanottajan tulee olettaa, että uudelleenyrityksiä tapahtuu, ja suunnitella niitä varten:
- Käytä tapahtumatunnistetta, jos se on saatavilla. Tallenna se yksilöllisen rajoitteen tai vastaavan deduplikointiavaimen kanssa.
- Tee käsittelystä idempotenttia. Saman toimitustilapäivityksen soveltaminen kahdesti ei saa lähettää kahta asiakasviestiä, luoda kahta hyvitystä tai siirtää tilausta virheellisesti eteenpäin.
- Säilytä alkuperäinen hyötykuorma tai hyödyllinen auditointitietue. Tämä tukee uudelleentoistoa, tutkimista ja täsmäytystä.
- Erota hyväksyminen ja käsittely. Työntekijä voi yrittää sisäisiä virheitä uudelleen pakottamatta lähettäjää toistamaan koko HTTP-vaihtoa.
- Tallenna vastauskoodit ja viive. 5xx-vastausten, aikakatkaisujen tai päällekkäisten tapahtumatunnisteiden lisääntyminen voi paljastaa katkoksen ennen kuin käyttäjät ilmoittavat puuttuvista seurantapäivityksistä.
Päällekkäisen tapahtuman pitäisi yleensä saada onnistumisvastaus, jos alkuperäinen tapahtuma oli jo hyväksytty pysyvästi. Virheen palauttaminen jokaisesta päällekkäisyydestä voi aiheuttaa tarpeettomia uudelleenyrityksiä. Päätepiste voi kirjata tapahtuman nähdyksi aiemmin, ohittaa toistetun liiketoimintatoiminnon ja palauttaa saman onnistumisluokan kuin uudelleen hyväksytylle tapahtumalle.
Milloin pitäisi palauttaa 4xx, 429 tai 5xx?
Palauta 4xx, kun saman pyynnön uudelleenyritys ei todennäköisesti korjaa ongelmaa. Esimerkkejä ovat virheellinen allekirjoitus, puuttuva pakollinen todennus, tukematon hyötykuorman rakenne tai pysyvää validointisääntöä rikkova pyyntö. Ennen 4xx-koodin valintaa tarkista, käsitteleekö lähettäjä kyseisen tilan pysyvänä virheenä. Joillakin alustoilla on omat sääntönsä epäonnistuneille toimituksille.
Käytä 429-koodia harkiten. HTTP määrittelee 429-koodin nopeusrajoitusta varten, ja Retry-After-otsake voi ilmoittaa, milloin uudelleenyritys saattaa olla sopiva. Kaikki webhook-lähettäjät eivät kuitenkaan tulkitse 429-koodia samalla tavalla. Jos jonosi on täynnä tai palvelusi ylikuormittunut, varmista, että palveluntarjoaja yrittää turvallisesti uudelleen eikä sen aikataulu pahenna ylikuormitusta. Rajattu vastaanottojono ja backpressure-suunnitelma ovat yleensä parempia kuin pyyntöjen ennakoimaton epäonnistuminen.
Palauta 5xx, kun vastaanottaja ei tilapäisen ongelman vuoksi voi hyväksyä tapahtumaa turvallisesti. Tämä sisältää käytöstä poissa olevan tietokannan, epäonnistuneen pysyvän jonokirjoituksen tai sisäisen virheen, joka esti validoinnin tai tallennuksen. Palauttamalla 200:n ja hylkäämällä tapahtuman hiljaisesti vaikeutat palautumista, koska lähettäjällä ei ole syytä yrittää uudelleen.
Vältä uudelleenohjauksia, kuten 301, 302 tai 307, webhook-toimituksissa. Uudelleenohjausten käsittely vaihtelee asiakkaiden välillä, ja allekirjoitetun pyynnön uudelleenohjaus voi aiheuttaa epäselvyyttä kohteesta, metodista ja rungosta. Määritä palveluntarjoajalle sen sijaan lopullinen HTTPS-päätepiste.
Luotettava vastauskäytäntö seurantatapahtumille
Useimmissa seuranta-webhook-integraatioissa seuraava käytäntö on järkevä lähtökohta:
- Palauta
200tai202, kun tapahtuma on todennettu ja tallennettu pysyvästi tai lisätty luotettavaan jonoon. - Palauta 4xx-vastaus virheellisestä allekirjoituksesta, todennuksesta tai pysyvästi käyttökelvottomasta hyötykuormasta palveluntarjoajan dokumentoitujen sääntöjen mukaisesti.
- Palauta 5xx, kun tilapäinen virhe estää pysyvän hyväksymisen.
- Palauta turvallisesti tunnistetusta päällekkäisestä tapahtumasta onnistumisvastaus ja estä päällekkäiset liiketoimintavaikutukset.
- Pidä käsittelijä nopeana ja mittaa sen kuittausviive.
- Testaa ennen tuotantoon siirtymistä aikakatkaisu-, uudelleenyritys-, päällekkäisyys-, vääräjärjestys-, virheellinen hyötykuorma- ja palveluntarjoajan katkostilanteet.
Jos integroit seuranta-API:n, aloita palveluntarjoajan webhook-dokumentaatiosta ja varmista hyväksytyt onnistumiskoodit, pyyntöjen allekirjoitusmenetelmä, aikakatkaisu, uudelleenyritysten laukaisimet, hyötykuorman skeema ja tapahtumatunniste. 17TRACK-integraatioissa virallinen Tracking API -dokumentaatio on oikea paikka palveluntarjoajakohtaisen sopimuksen tarkistamiseen sen sijaan, että se pääteltäisiin yleisestä HTTP-käytännöstä.
Toteutuksen tarkistuslista
- Päätepiste on saavutettavissa HTTPS:n kautta ja sillä on vakaa tuotanto-URL.
- Todennus ja allekirjoituksen tarkistus tehdään ennen liiketoimintakäsittelyä.
- Raakapyyntö tai todennettava esitys säilytetään tarvittaessa allekirjoitusten tarkistamista ja vianmääritystä varten.
- Tapahtuma tallennetaan ennen onnistumisvastauksen lähettämistä.
- Päällekkäiset toimitukset ovat turvallisia eivätkä toista peruuttamattomia toimintoja.
- Työntekijät voivat yrittää sisäistä käsittelyä uudelleen riippumatta lähettäjän HTTP-uudelleenyrityssyklistä.
- Lokeihin sisältyvät tapahtumatunnus, toimitusaika, vastauskoodi, käsittelytila ja korrelaatiotunnus ilman salaisuuksien paljastamista.
- Hälytykset erottavat päätepisteen aikakatkaisut, 4xx-validointivirheet, 5xx-katkokset, jonoviiveet ja päällekkäiset toimitukset.
- Dokumentoitu palveluntarjoajan toiminta on testattu oikeilla tai testiympäristön tapahtumilla.
Usein kysytyt kysymykset
Onko 200 OK parempi kuin 202 Accepted webhookille?
Ei kumpikaan ole yleisesti parempi. Käytä 200 OK -vastausta, kun pyyntö on hyväksytty ja integraatiosi käsittelee vastauksen yleisenä onnistumisena. Käytä 202 Accepted -vastausta, kun tapahtuma on hyväksytty asynkronista käsittelyä varten. Varmista, että lähettäjä luokittelee valitun 2xx-vastauksen onnistuneeksi.
Pitäisikö webhook-päätepisteen odottaa, kunnes seurantapäivitys on kokonaan käsitelty?
Yleensä ei. Sen pitäisi odottaa vain siihen asti, että tapahtuma on todennettu, validoitu ja hyväksytty pysyvästi. Pitkäkestoisen työn pitäisi yleensä tapahtua kuittauksen jälkeen, jotta hidas riippuvuus ei aiheuta vältettävissä olevaa aikakatkaisua ja uudelleenyritystä.
Mitä pitäisi tapahtua, kun sama seurantatapahtuma saapuu kahdesti?
Tunnista se palveluntarjoajan tapahtumatunnisteen tai huolellisesti suunnitellun vastaavan avaimen avulla, ohita päällekkäiset sivuvaikutukset ja palauta onnistumisvastaus, jos tapahtuma oli jo hyväksytty. Näin uudelleenyritykset ovat turvallisia ilman uusien käsittelyvirheiden piilottamista.
Pitäisikö virheellinen allekirjoitus palauttaa 400 vai 401?
Valinta riippuu todennusmallistasi ja palveluntarjoajan dokumentoiduista odotuksista. Molemmat voivat ilmoittaa hylkäyksestä, mutta johdonmukaisuus on tärkeämpää kuin yhden koodin yleinen valinta. Älä kuittaa tapahtumaa, jonka aitoutta et voi varmistaa.
Aiheuttaako 5xx-vastaus aina uudelleenyrityksen?
Ei. Monet webhook-järjestelmät yrittävät uudelleen aikakatkaisujen ja palvelinvirheiden jälkeen, mutta laukaisimet ja aikataulut ovat palveluntarjoajakohtaisia. Käsittele uudelleenyrityksiä dokumentoituna integraatiokäyttäytymisenä ja varmista ne testiympäristössä.
Lähteet
- RFC 9110: HTTP Semantics — onnistumis-, asiakasvirhe-, palvelinvirhe-, uudelleenohjaus- ja vastauskäsittelyjen määritelmät.
- RFC 6585: Additional HTTP Status Codes —
429 Too Many Requests-koodin määrittely. - Stripe Webhooks Documentation — käytännön ohjeita webhook-vastauksista, asynkronisesta käsittelystä ja päällekkäisten tapahtumien käsittelystä.
- GitHub Docs: Handling Webhook Deliveries — toimitusten tarkastelu ja webhook-integraatioiden operatiiviset näkökohdat.
- 17TRACK Tracking API Documentation — palveluntarjoajakohtainen dokumentaatio seuranta-API-integraatioiden toteuttamista varten.


