Ką turėtų grąžinti sekimo webhook galinis taškas? Būsenos kodai, skirtojo laiko limitai ir pakartotiniai bandymai?
Stebėjimo webhook galinis taškas, priėmęs įvykį apdoroti, turėtų grąžinti greitą, sąmoningai pasirinktą 2xx atsaką. Daugumoje integracijų saugiausia seka yra autentifikuoti užklausą, patikrinti naudingąją apkrovą, išsaugoti arba įtraukti į eilę įvykį ir patvirtinti jo priėmimą atsaku 200 OK arba 202 Accepted. Naudokite 4xx atsakus užklausoms, kurių siuntėjas neturėtų bandyti dar kartą, o 5xx atsakus – kai laikina serverio problema sutrukdė priimti užklausą. Tikslus skirtasis laikas ir pakartotinių bandymų elgsena vis tiek priklauso nuo webhook teikėjo sutarties, todėl įgyvendinimas turėtų būti grindžiamas dokumentuota siuntėjo elgsena, o ne prielaidomis.
Stebėjimo arba siuntos būsenos webhook atveju šis skirtumas svarbus, nes pristatymo įvykiai gali būti gauti daugiau nei vieną kartą, ne eilės tvarka arba pakartoti po tinklo sutrikimo. Galinio taško užduotis nebūtinai yra užbaigti kiekvieną verslo operaciją prieš atsakant. Pirmiausia jis turi patikimai nuspręsti, ar įvykis priimtas.
Atsako sutartis praktikoje
Webhook atsakas turi dvi auditorijas: siunčiančią sistemą ir jūsų programą. Siuntėjui reikia aiškaus HTTP rezultato, kad jis galėtų nuspręsti, ar pažymėti pristatymą kaip sėkmingą, bandyti dar kartą, ar sustoti. Jūsų programai reikia pakankamai laiko įvykiui patikrinti ir patikimai įrašyti. Šiuos tikslus lengviau pasiekti, kai galinis taškas turi trumpą sinchroninį kelią ir atskirą asinchroninio apdorojimo kelią.
- Gaukite HTTP užklausą per HTTPS.
- Patikrinkite parašą, autentifikavimo duomenis, laiko žymą ar kitus teikėjo reikalaujamus užklausos vientisumo valdiklius.
- Išanalizuokite ir patikrinkite naudingąją apkrovą neatlikdami lėtų tolesnių operacijų.
- Įrašykite įvykį arba dublikatų pašalinimo įrašą ir įvykio nuorodą į patikimą saugyklą ar patikimą eilę.
- Grąžinkite sąmoningai pasirinktą 2xx atsaką.
- Asinchroniškai apdorokite stebėjimo atnaujinimą, kliento pranešimą, atsargų pakeitimą ar kitą verslo veiksmą.
Atsakas neturėtų teigti, kad įvykis priimtas, jei jis egzistuoja tik proceso atmintyje. Jei programa iškart po sėkmės atsako sugenda, niekada neišsaugotas įvykis gali būti prarastas, o siuntėjas manys, kad pristatymas buvo sėkmingas. Todėl 2xx grąžinimo momentas turėtų atitikti jūsų faktinę patikimo išsaugojimo garantiją.
Kokį būsenos kodą turėtų grąžinti webhook?
| Atsakas | Reikšmė siuntėjui | Įprastas webhook naudojimas |
|---|---|---|
200 OK | Užklausa priimta ir sėkmingai apdorota. | Praktiškas numatytasis pasirinkimas po patikrinimo ir patikimo priėmimo. |
202 Accepted | Užklausa priimta apdoroti, tačiau darbas gali tęstis. | Naudinga, kai įvykis saugiai įtrauktas į eilę, bet verslo apdorojimas vyksta asinchroniškai. |
204 No Content | Užklausa sėkminga ir atsako turinys nereikalingas. | Tinka, kai teikėjas priima tuščią sėkmės atsaką. |
400–499 | Užklausa negaliojanti, neautorizuota arba pateikta nepriimtinu formatu. | Netinkama naudingoji apkrova, nepavykęs autentifikavimas, netinkamas parašas arba visam laikui atmestas įvykis. |
429 Too Many Requests | Gavėjas taiko dažnio ribojimą. | Naudokite tik tada, kai siuntėjo pakartotinių bandymų elgsena ir jūsų dažnio ribojimo politika dera tarpusavyje. |
500–599 | Gavėjas negalėjo priimti užklausos dėl serverio arba laikinos problemos. | Duomenų bazės sutrikimas, eilės klaida, priklausomybės sutrikimas arba netikėta programos klaida. |
200 OK dažnai yra mažiausiai netikėtas pasirinkimas, nes jis plačiai suprantamas kaip sėkmingas gavimas. 202 Accepted taip pat semantiškai naudingas, kai galinis taškas priėmė įvykį vėlesniam apdorojimui. Nė vienas kodas nėra automatiškai teisingas: siuntėjo dokumentacijoje gali būti nurodyta, kurie 2xx atsakai laikomi sėkmingais, o kai kurie teikėjai gali tikėtis konkretaus turinio arba turinio tipo.
Negrąžinkite 2xx atsako vien todėl, kad HTTP užklausa pasiekė jūsų serverį. Jei parašo patikrinimas nepavyko arba naudingosios apkrovos neįmanoma saugiai interpretuoti, 4xx atsakas paprastai yra tikslesnis. Kita vertus, negrąžinkite 4xx dėl laikino duomenų bazės sutrikimo, jei įvykis galėtų būti sėkmingas vėliau. 5xx atsakas suteikia pakartotinius bandymus palaikančiam siuntėjui galimybę dar kartą pristatyti įvykį, nors teikėjas gali taikyti savo politiką.
Kaip reikėtų tvarkyti skirtuosius laikus?
Webhook skirtieji laikai priklauso nuo teikėjo. Nėra universalaus HTTP skirtojo laiko, kurį naudotų kiekviena stebėjimo platforma, o siuntėjas gali nustoti laukti anksčiau, nei jūsų programa baigs lėtą operaciją. Laikykite siuntėjo dokumentuotą skirtąjį laiką maksimalia riba, o ne tikslu. Jūsų galinis taškas paprastai turėtų atsakyti gerokai anksčiau už šią ribą.
Dažniausia projektavimo klaida – atlikti visą tolesnį darbą prieš patvirtinant webhook. Apdorojimo priemonė gali paeiliui iškviesti duomenų bazę, užsakymų valdymo sistemą, pranešimų tarnybą ir analizės konvejerį. Dėl vienos lėtos priklausomybės siuntėjas gali pamatyti skirtąjį laiką, nors jūsų programa galiausiai užbaigs darbą. Tada siuntėjas gali bandyti dar kartą, sukeldamas pasikartojantį apdorojimą arba konkuruojančius atnaujinimus.
Sinchroninį kelią apribokite darbu, būtinu saugiam priėmimo sprendimui. Paprastai tai apima užklausos autentifikavimą, pagrindinį schemos patikrinimą, patikimą įvykio saugojimą ir paskelbimą eilėje. Brangų papildomą duomenų gavimą, vežėjų paieškas, klientų pranešimus ir trečiųjų šalių API iškvietimus perduokite vykdytojui. Atskirai stebėkite laiką, praleistą gaunant, tikrinant, išsaugant ir patvirtinant įvykį, bei laiką, praleistą jį apdorojant.
Skirtasis laikas nėra tas pats, kas nepavykusi verslo operacija. Siuntėjo požiūriu, skirtasis laikas paprastai reiškia, kad jis negavo tinkamo sėkmės atsako. Jūsų tarnyba galėjo sėkmingai išsaugoti įvykį prieš pat ryšio nutrūkimą. Todėl idempotentiškumas ir dublikatų pašalinimas būtini net tada, kai galinis taškas atrodo patikimas.
Kas sukelia pakartotinius bandymus?
Webhook siuntėjas gali bandyti dar kartą po ryšio klaidos, skirtojo laiko arba atsako, kurį jo sutartis priskiria nesėkmingiems. Tikslus grafikas, maksimalus bandymų skaičius, delsos algoritmas ir pristatymo laikotarpis priklauso nuo teikėjo. Nežadėkite fiksuoto pakartotinių bandymų skaičiaus, nebent jis nurodytas teikėjo dokumentacijoje.
Gavėjas turėtų manyti, kad pakartotiniai bandymai galimi, ir sąmoningai tam pasiruošti:
- Jei įmanoma, naudokite įvykio identifikatorių. Išsaugokite jį su unikalia sąlyga arba lygiaverčiu dublikatų pašalinimo raktu.
- Apdorojimą paverskite idempotentišku. Du kartus pritaikius tą patį pristatymo būsenos atnaujinimą neturėtų būti siunčiami du pranešimai klientui, kuriamos dvi grąžinamosios išmokos ar neteisingai keičiamas užsakymo etapas.
- Išsaugokite pradinę naudingąją apkrovą arba naudingą audito įrašą. Tai padeda pakartoti, ištirti ir suderinti duomenis.
- Atskirkite priėmimą nuo apdorojimo. Vykdytojas gali pakartoti vidinių klaidų apdorojimą, nepriversdamas siuntėjo kartoti viso HTTP apsikeitimo.
- Įrašykite atsako kodus ir delsą. Išaugęs 5xx atsakų, skirtųjų laikų arba pasikartojančių įvykių ID skaičius gali atskleisti sutrikimą dar prieš naudotojams pranešant apie trūkstamus stebėjimo atnaujinimus.
Pasikartojantis įvykis paprastai turėtų gauti sėkmingą atsaką, jei pradinis įvykis jau buvo patikimai priimtas. Grąžinant klaidą kiekvienam dublikatui gali būti sukelti nereikalingi pakartotiniai bandymai. Galinis taškas gali įrašyti, kad įvykis jau buvo matytas, praleisti pakartotinį verslo veiksmą ir grąžinti tą pačią sėkmės klasę, kuri naudojama naujai priimtam įvykiui.
Kada grąžinti 4xx, 429 arba 5xx?
Grąžinkite 4xx, kai mažai tikėtina, kad pakartojus tą pačią užklausą problema bus išspręsta. Pavyzdžiai: netinkamas parašas, trūkstamas būtinas autentifikavimas, nepalaikoma naudingosios apkrovos forma arba užklausa, pažeidžianti nuolatinę tikrinimo taisyklę. Prieš pasirinkdami 4xx patikrinkite, ar siuntėjas šią būseną laiko nuolatine klaida. Kai kurios platformos turi savo nesėkmingų pristatymų taisykles.
429 naudokite atsargiai. HTTP apibrėžia 429 dažnio ribojimui, o antraštė Retry-After gali nurodyti, kada pakartotinis bandymas būtų tinkamas. Tačiau ne kiekvienas webhook siuntėjas 429 interpretuoja vienodai. Jei eilė pilna arba jūsų tarnyba perkrauta, įsitikinkite, kad teikėjas bandys saugiai dar kartą ir kad jo pakartotinių bandymų grafikas nepablogins perkrovos. Apribota priėmimo eilė ir apkrovos slėgio valdymo planas paprastai yra geresni nei leidimas užklausoms nenuspėjamai žlugti.
Grąžinkite 5xx, kai gavėjas dėl laikinos problemos negali saugiai priimti įvykio. Tai apima nepasiekiamą duomenų bazę, nepavykusį patikimą įrašymą į eilę arba vidinę klaidą, sutrukdžiusią patikrinti ar išsaugoti duomenis. Grąžinant 200 ir tyliai atmetant įvykį atkūrimas tampa sudėtingesnis, nes siuntėjas neturi priežasties bandyti dar kartą.
Venkite peradresavimų, tokių kaip 301, 302 arba 307, naudojimo webhook pristatymui. Skirtingi klientai peradresavimus tvarko nevienodai, o pasirašytos užklausos peradresavimas gali sukelti neaiškumų dėl paskirties, metodo ir turinio. Vietoje to sukonfigūruokite teikėją naudoti galutinį HTTPS galinį tašką.
Patikima stebėjimo įvykių atsakų politika
Daugumai stebėjimo webhook integracijų ši politika yra tinkamas pradinis taškas:
- Grąžinkite
200arba202, kai įvykis autentifikuotas ir patikimai išsaugotas arba įtrauktas į patikimą eilę. - Grąžinkite 4xx atsaką dėl netinkamo parašo, netinkamo autentifikavimo arba visam laikui netinkamos naudingosios apkrovos, laikydamiesi dokumentuotų teikėjo taisyklių.
- Grąžinkite 5xx, kai laikina klaida neleidžia patikimai priimti įvykio.
- Saugiai atpažintam dublikatui grąžinkite sėkmės atsaką ir neleiskite pasikartojantiems verslo veiksmams.
- Laikykite apdorojimo priemonę greitą ir matuokite jos patvirtinimo delsą.
- Prieš paleisdami į produkciją išbandykite skirtojo laiko, pakartotinių bandymų, dublikatų, įvykių ne eilės tvarka, netinkamų duomenų ir teikėjo sutrikimo scenarijus.
Jei integruojate stebėjimo API, pradėkite nuo teikėjo webhook dokumentacijos ir patvirtinkite priimtinus sėkmės kodus, užklausų pasirašymo metodą, skirtąjį laiką, pakartotinių bandymų priežastis, naudingosios apkrovos schemą ir įvykio identifikatorių. 17TRACK integracijoms tinkama vieta patikrinti konkretaus teikėjo sutartį, o ne spręsti pagal bendrą HTTP praktiką, yra oficiali Tracking API dokumentacija.
Įgyvendinimo kontrolinis sąrašas
- Galinį tašką galima pasiekti per HTTPS ir jis turi stabilų produkcinį URL.
- Autentifikavimas ir parašo tikrinimas atliekami prieš verslo apdorojimą.
- Neapdorota užklausa arba patikrinamas jos atvaizdas išsaugomas, kai to reikia parašams tikrinti ir trikčių diagnostikai.
- Įvykis išsaugomas prieš siunčiant sėkmės atsaką.
- Pasikartojantys pristatymai yra saugūs ir nekartoja negrįžtamų veiksmų.
- Vykdytojai gali pakartoti vidinį apdorojimą nepriklausomai nuo siuntėjo HTTP pakartotinių bandymų ciklo.
- Žurnaluose pateikiamas įvykio ID, pristatymo laikas, atsako kodas, apdorojimo būsena ir koreliacijos ID, neatskleidžiant paslapčių.
- Įspėjimuose atskiriami galinio taško skirtieji laikai, 4xx tikrinimo klaidos, 5xx sutrikimai, eilės delsos ir pasikartojantys pristatymai.
- Dokumentuota teikėjo elgsena išbandyta su tikrais arba smėlio dėžės įvykiais.
DUK
Ar 200 OK yra geresnis už 202 Accepted webhook atveju?
Nė vienas nėra visuotinai geresnis. Naudokite 200 OK, kai užklausa priimta ir jūsų integracija atsaką laiko bendru sėkmės atsaku. Naudokite 202 Accepted, kai įvykis priimtas asinchroniniam apdorojimui. Patvirtinkite, kad siuntėjas pasirinktą 2xx atsaką klasifikuoja kaip sėkmingą.
Ar webhook galinis taškas turėtų laukti, kol stebėjimo atnaujinimas bus visiškai apdorotas?
Paprastai ne. Jis turėtų laukti tik tol, kol įvykis bus autentifikuotas, patikrintas ir patikimai priimtas. Ilgai trunkantis darbas paprastai turėtų vykti po patvirtinimo, kad lėta priklausomybė nesukeltų išvengiamo skirtojo laiko ir pakartotinio bandymo.
Kas turėtų nutikti, kai tas pats stebėjimo įvykis gaunamas du kartus?
Atpažinkite jį pagal teikėjo įvykio ID arba kruopščiai sukurtą lygiavertį raktą, praleiskite pasikartojančius šalutinius veiksmus ir grąžinkite sėkmės atsaką, jei įvykis jau buvo priimtas. Taip pakartotiniai bandymai tampa saugūs, neslepiant naujų apdorojimo klaidų.
Ar netinkamas parašas turėtų grąžinti 400 ar 401?
Pasirinkimas priklauso nuo jūsų autentifikavimo modelio ir dokumentuotų teikėjo lūkesčių. Abu kodai gali perduoti atmetimą, tačiau nuoseklumas svarbesnis už vieno universalaus kodo pasirinkimą. Nepatvirtinkite įvykio, kurio autentiškumo negalite patikrinti.
Ar 5xx atsakas visada sukelia pakartotinį bandymą?
Ne. Daugelis webhook sistemų pakartoja bandymus po skirtųjų laikų ir serverio klaidų, tačiau pakartotinių bandymų priežastys ir grafikai priklauso nuo teikėjo. Laikykite pakartotinius bandymus dokumentuota integracijos elgsena ir patikrinkite ją testavimo aplinkoje.
Šaltiniai
- RFC 9110: HTTP Semantics — sėkmės, kliento klaidų, serverio klaidų, peradresavimo ir atsakų tvarkymo apibrėžtys.
- RFC 6585: Additional HTTP Status Codes —
429 Too Many Requestsspecifikacija. - Stripe Webhooks Documentation — praktinės rekomendacijos dėl webhook atsakų, asinchroninio apdorojimo ir pasikartojančių įvykių tvarkymo.
- GitHub Docs: Handling Webhook Deliveries — webhook integracijų pristatymų tikrinimas ir veiklos aspektai.
- 17TRACK Tracking API Documentation — konkretaus teikėjo dokumentacija, kurią reikia patikrinti diegiant stebėjimo API integracijas.


