Skip to main content
DomovBlogPríručkyČo by mal endpoint webhooku na sledovanie vracať? Stavové kódy, časové limity a opakovania?

Čo by mal endpoint webhooku na sledovanie vracať? Stavové kódy, časové limity a opakovania?

17TRACK

Akonáhle koncový bod webhooku na sledovanie prijme udalosť na spracovanie, mal by vrátiť rýchlu a zámernú odpoveď 2xx. Vo väčšine integrácií je najbezpečnejším postupom autentifikovať požiadavku, overiť payload, uložiť alebo zaradiť udalosť do frontu a potvrdiť ju pomocou 200 OK alebo 202 Accepted. Kódy 4xx používajte pre požiadavky, ktoré by odosielateľ nemal opakovať, a kódy 5xx v prípade, že dočasný problém na strane servera zabránil prijatiu. Presné správanie pri časových limitoch a opakovaní stále závisí od zmluvných podmienok poskytovateľa webhooku, preto by mala byť implementácia navrhnutá podľa zdokumentovaného správania odosielateľa, nie podľa predpokladov.

Aké stavové kódy a časové limity by mal vrátiť koncový bod webhooku na sledovanie

Pri webhooku na sledovanie alebo stav zásielky je toto rozlíšenie dôležité, pretože doručovacie udalosti môžu prísť viackrát, v nesprávnom poradí alebo môžu byť po zlyhaní siete znovu prehrané. Úlohou koncového bodu nemusí byť dokončenie každej obchodnej operácie ešte pred odpoveďou. Jeho prvou úlohou je spoľahlivo rozhodnúť, či bola udalosť prijatá.

Zmluva o odpovedi v praxi

Odpoveď webhooku má dve skupiny príjemcov: odosielajúci systém a vašu vlastnú aplikáciu. Odosielateľ potrebuje jednoznačný výsledok HTTP, aby mohol rozhodnúť, či doručenie označí ako úspešné, zopakuje ho alebo ho ukončí. Vaša aplikácia potrebuje dostatok času na overenie a trvalé zaznamenanie udalosti. Tieto ciele sa ľahšie dosahujú, keď má koncový bod krátku synchronnú cestu a samostatnú asynchrónnu cestu spracovania.

  1. Prijmite požiadavku HTTP cez HTTPS.
  2. Skontrolujte podpis, autentifikačné údaje, časovú pečiatku alebo iné kontroly integrity požiadavky vyžadované poskytovateľom.
  3. Analyzujte a overte payload bez vykonávania pomalých následných operácií.
  4. Zapíšte udalosť alebo záznam deduplikácie a referenciu na udalosť do trvalého úložiska alebo spoľahlivého frontu.
  5. Vráťte zámernú odpoveď 2xx.
  6. Asynchrónne spracujte aktualizáciu sledovania, upozornenie zákazníka, zmenu zásob alebo inú obchodnú akciu.

Odpoveď by nemala tvrdiť, že udalosť bola prijatá, ak existuje iba v pamäti procesu. Ak aplikácia bezprostredne po vrátení úspechu spadne, udalosť, ktorá nebola uložená, sa môže stratiť, zatiaľ čo odosielateľ bude považovať doručenie za úspešné. Okamih, v ktorom vraciate 2xx, by preto mal zodpovedať vašej skutočnej záruke trvalosti.

Aký stavový kód by mal webhook vrátiť?

OdpoveďVýznam pre odosielateľaTypické použitie webhooku
200 OKPožiadavka bola prijatá a úspešne spracovaná.Praktická predvolená voľba po overení a trvalom prijatí.
202 AcceptedPožiadavka bola prijatá na spracovanie, ale práca môže pokračovať.Užitočné, keď bola udalosť bezpečne zaradená do frontu, ale obchodné spracovanie je asynchrónne.
204 No ContentPožiadavka bola úspešná a telo odpovede nie je potrebné.Vhodné, keď poskytovateľ akceptuje prázdnu úspešnú odpoveď.
400–499Požiadavka je neplatná, neoprávnená alebo v odoslanej podobe neprijateľná.Chybne vytvorený payload, neúspešná autentifikácia, neplatný podpis alebo trvalo odmietnutá udalosť.
429 Too Many RequestsPríjemca uplatňuje obmedzenie rýchlosti.Použite iba vtedy, keď sú správanie odosielateľa pri opakovaní a vaša politika obmedzenia rýchlosti kompatibilné.
500–599Príjemca nemohol požiadavku prijať pre problém na strane servera alebo dočasný problém.Výpadok databázy, zlyhanie frontu, zlyhanie závislosti alebo neočakávaná chyba aplikácie.

200 OK je často najmenej prekvapivou voľbou, pretože sa všeobecne chápe ako úspešné prijatie. 202 Accepted je tiež sémanticky užitočné, keď koncový bod prijal udalosť na neskoršie spracovanie. Ani jeden kód nie je automaticky správny: dokumentácia odosielateľa môže určovať, ktoré odpovede 2xx sa považujú za úspešné, a niektorí poskytovatelia môžu vyžadovať konkrétne telo alebo typ obsahu.

Nevracajte odpoveď 2xx len preto, že požiadavka HTTP dorazila na váš server. Ak overenie podpisu zlyhá alebo payload nemožno bezpečne interpretovať, odpoveď 4xx je zvyčajne pravdivejšia. Naopak, nevracajte 4xx pri dočasnom výpadku databázy, ak by udalosť mohla neskôr uspieť. Odpoveď 5xx dáva odosielateľovi podporujúcemu opakovanie možnosť doručiť udalosť znova, hoci poskytovateľ môže uplatňovať vlastnú politiku.

Ako riešiť časové limity?

Hodnoty časových limitov webhooku sú špecifické pre poskytovateľa. Neexistuje univerzálny časový limit HTTP, ktorý používa každá platforma na sledovanie, a odosielateľ môže prestať čakať skôr, než vaša aplikácia dokončí pomalú operáciu. Zdokumentovaný časový limit odosielateľa považujte za maximálnu hranicu, nie za cieľ. Váš koncový bod by mal zvyčajne odpovedať výrazne pred touto hranicou.

Najčastejšou konštrukčnou chybou je vykonávanie všetkých následných operácií pred potvrdením webhooku. Handler môže postupne volať databázu, systém správy objednávok, službu upozornení a analytický kanál. Jedna pomalá závislosť môže spôsobiť, že odosielateľ zaznamená časový limit, hoci vaša aplikácia prácu nakoniec dokončí. Odosielateľ potom môže požiadavku zopakovať, čo vytvorí duplicitné spracovanie alebo konkurenčné aktualizácie.

Synchronnú cestu obmedzte na prácu potrebnú na bezpečné rozhodnutie o prijatí. Zvyčajne zahŕňa autentifikáciu požiadavky, základné overenie schémy, trvalé uloženie udalosti a publikovanie do frontu. Náročné obohacovanie údajov, vyhľadávanie u prepravcov, komunikáciu so zákazníkmi a volania API tretích strán presuňte na workera. Samostatne sledujte čas prijímania, overovania, ukladania a potvrdenia udalosti a čas jej spracovania.

Časový limit nie je to isté ako neúspešná obchodná operácia. Z pohľadu odosielateľa časový limit zvyčajne znamená, že nedostal použiteľnú úspešnú odpoveď. Vaša služba mohla udalosť úspešne uložiť tesne pred uzavretím spojenia. Preto sú idempotencia a deduplikácia potrebné aj vtedy, keď sa koncový bod javí ako spoľahlivý.

Čo spôsobuje opakovanie?

Odosielateľ webhooku môže opakovať doručenie po chybe spojenia, prekročení časového limitu alebo odpovedi, ktorú jeho zmluva klasifikuje ako neúspešnú. Presný harmonogram, maximálny počet pokusov, algoritmus oneskorenia a časové okno doručenia sa líšia podľa poskytovateľa. Nesľubujte pevný počet opakovaní, pokiaľ nie je uvedený v dokumentácii poskytovateľa.

Príjemca by mal predpokladať, že k opakovaniam môže dôjsť, a cielene sa na ne pripraviť:

  • Ak je k dispozícii, používajte identifikátor udalosti. Uložte ho s jedinečným obmedzením alebo ekvivalentným kľúčom deduplikácie.
  • Spracovanie musí byť idempotentné. Dvojnásobné použitie rovnakej aktualizácie stavu doručenia by nemalo odoslať dve správy zákazníkovi, vytvoriť dve refundácie ani nesprávne posunúť objednávku.
  • Uchovajte pôvodný payload alebo užitočný auditný záznam. Podporí to opätovné prehranie, vyšetrovanie a zosúladenie.
  • Oddeľte prijatie od spracovania. Worker môže opakovať interné zlyhania bez toho, aby nútil odosielateľa opakovať celú výmenu HTTP.
  • Zaznamenávajte stavové kódy a latenciu. Nárast odpovedí 5xx, časových limitov alebo duplicitných ID udalostí môže odhaliť výpadok skôr, než používatelia nahlásia chýbajúce aktualizácie sledovania.

Duplicitná udalosť by mala zvyčajne dostať úspešnú odpoveď, ak bola pôvodná udalosť už trvalo prijatá. Vrátenie chyby pri každej duplicite môže vyvolať zbytočné opakovania. Koncový bod môže zaznamenať, že udalosť už bola prijatá, preskočiť opakovanú obchodnú akciu a vrátiť rovnakú triedu úspechu, aká sa používa pri novo prijatej udalosti.

Kedy vrátiť 4xx, 429 alebo 5xx?

4xx vráťte vtedy, keď opakovanie rovnakej požiadavky pravdepodobne problém nevyrieši. Patria sem neplatný podpis, chýbajúca požadovaná autentifikácia, nepodporovaný tvar payloadu alebo požiadavka porušujúca trvalé validačné pravidlo. Pred výberom 4xx skontrolujte, či odosielateľ považuje tento stav za trvalé zlyhanie. Niektoré platformy majú vlastné pravidlá pre neúspešné doručenia.

Kód 429 používajte opatrne. HTTP definuje 429 pre obmedzenie rýchlosti a hlavička Retry-After môže oznámiť, kedy môže byť opakovanie vhodné. Nie každý odosielateľ webhooku však interpretuje 429 rovnako. Ak je váš front plný alebo je služba preťažená, overte, či poskytovateľ bude bezpečne opakovať požiadavky a či jeho harmonogram opakovaní preťaženie nezhorší. Obmedzený vstupný front a plán spätného tlaku sú zvyčajne lepšie než nepredvídateľné zlyhávanie požiadaviek.

5xx vráťte vtedy, keď príjemca nemôže bezpečne prijať udalosť pre dočasný problém. Zahŕňa to nedostupnú databázu, zlyhaný zápis do trvalého frontu alebo internú chybu, ktorá zabránila overeniu či uloženiu. Vrátenie 200 pri tichom zahodení udalosti sťažuje obnovu, pretože odosielateľ nemá dôvod skúsiť doručenie znova.

Nespoliehajte sa pri doručovaní webhooku na presmerovania, ako sú 301, 302 alebo 307. Spracovanie presmerovaní sa medzi klientmi líši a presmerovanie podpísanej požiadavky môže spôsobiť nejasnosti týkajúce sa cieľa, metódy a tela. Namiesto toho nastavte u poskytovateľa konečný koncový bod HTTPS.

Spoľahlivá politika odpovedí pre udalosti sledovania

Pre väčšinu integrácií webhookov na sledovanie je vhodným východiskom nasledujúca politika:

  1. Vráťte 200 alebo 202 po tom, ako udalosť prešla autentifikáciou a bola trvalo uložená alebo umiestnená do spoľahlivého frontu.
  2. Vráťte odpoveď 4xx pri neplatnom podpise, neplatnej autentifikácii alebo trvalo nepoužiteľnom payloade podľa zdokumentovaných pravidiel poskytovateľa.
  3. Vráťte 5xx, keď dočasné zlyhanie zabráni trvalému prijatiu.
  4. Pri bezpečne rozpoznanej duplicite vráťte úspešnú odpoveď a zabráňte duplicitným obchodným účinkom.
  5. Handler udržujte rýchly a merajte latenciu jeho potvrdenia.
  6. Pred spustením do produkcie otestujte scenáre časového limitu, opakovania, duplicity, nesprávneho poradia, chybného formátu a výpadku poskytovateľa.

Ak integrujete sledovacie API, začnite dokumentáciou webhooku poskytovateľa a overte akceptované úspešné kódy, spôsob podpisovania požiadaviek, časový limit, spúšťače opakovania, schému payloadu a identifikátor udalosti. Pri integráciách 17TRACK je vhodným miestom na overenie zmluvných podmienok špecifických pre poskytovateľa oficiálna dokumentácia Tracking API, nie odvodzovanie týchto podmienok zo všeobecnej praxe HTTP.

Kontrolný zoznam implementácie

  • Koncový bod je dostupný cez HTTPS a má stabilnú produkčnú URL.
  • Autentifikácia a overenie podpisu prebiehajú pred obchodným spracovaním.
  • Surová požiadavka alebo overiteľná reprezentácia sa uchováva tam, kde je to potrebné na kontrolu podpisov a riešenie problémov.
  • Udalosť sa uloží pred odoslaním úspešnej odpovede.
  • Duplicitné doručenia sú bezpečné a neopakujú nezvratné akcie.
  • Workery môžu opakovať interné spracovanie nezávisle od cyklu opakovaní HTTP zo strany odosielateľa.
  • Protokoly obsahujú ID udalosti, čas doručenia, stavový kód, stav spracovania a korelačné ID bez odhalenia tajomstiev.
  • Upozornenia rozlišujú časové limity koncového bodu, validačné zlyhania 4xx, výpadky 5xx, oneskorenia frontu a duplicitné doručenia.
  • Zdokumentované správanie poskytovateľa bolo otestované na skutočných alebo sandboxových udalostiach.

Často kladené otázky

Je 200 OK pre webhook lepšie ako 202 Accepted?

Žiadny z nich nie je všeobecne lepší. Použite 200 OK, keď bola požiadavka prijatá a vaša integrácia považuje odpoveď za všeobecný úspech. Použite 202 Accepted, keď bola udalosť prijatá na asynchrónne spracovanie. Overte, že odosielateľ zvolenú odpoveď 2xx klasifikuje ako úspešnú.

Mal by koncový bod webhooku čakať, kým sa aktualizácia sledovania úplne spracuje?

Zvyčajne nie. Mal by čakať iba dovtedy, kým bude udalosť autentifikovaná, overená a trvalo prijatá. Dlhšie trvajúca práca by sa mala zvyčajne vykonať po potvrdení, aby pomalá závislosť nespôsobila zbytočný časový limit a opakovanie.

Čo sa má stať, keď rovnaká udalosť sledovania príde dvakrát?

Rozpoznajte ju pomocou ID udalosti poskytovateľa alebo starostlivo navrhnutého ekvivalentného kľúča, preskočte duplicitné vedľajšie účinky a vráťte úspešnú odpoveď, ak bola udalosť už prijatá. Opakovania tak budú bezpečné bez skrytia nových zlyhaní spracovania.

Má neplatný podpis vrátiť 400 alebo 401?

Výber závisí od vášho autentifikačného modelu a zdokumentovaných očakávaní poskytovateľa. Obe možnosti môžu vyjadriť odmietnutie, no konzistentnosť je dôležitejšia než univerzálny výber jedného kódu. Nepotvrdzujte udalosť, ktorej pravosť nedokážete overiť.

Spôsobí odpoveď 5xx vždy opakovanie?

Nie. Mnohé systémy webhookov opakujú doručenie po prekročení časového limitu a pri chybách servera, no spúšťače a harmonogramy opakovaní sú špecifické pre poskytovateľa. Opakovania považujte za zdokumentované správanie integrácie a overte ich v testovacom prostredí.

Zdroje