Skip to main content
DomůBlogPrůvodciCo by měl endpoint webhooku pro sledování vracet? Stavové kódy, časové limity a opakované pokusy?

Co by měl endpoint webhooku pro sledování vracet? Stavové kódy, časové limity a opakované pokusy?

17TRACK

Koncový bod webhooku pro sledování by měl po přijetí události ke zpracování vrátit rychlou a záměrnou odpověď 2xx. Ve většině integrací je nejbezpečnějším postupem ověřit požadavek, zkontrolovat payload, uložit nebo zařadit událost do fronty a potvrdit její přijetí pomocí 200 OK nebo 202 Accepted. Odpovědi 4xx používejte pro požadavky, které by odesílatel neměl opakovat, a odpovědi 5xx tehdy, když dočasný problém na straně serveru zabránil přijetí požadavku. Přesné chování timeoutů a opakování stále závisí na smluvních podmínkách poskytovatele webhooku, proto by vaše implementace měla vycházet z dokumentovaného chování odesílatele, nikoli z předpokladů.

Jaké stavové kódy a timeouty by měl vracet koncový bod webhooku pro sledování

U webhooku pro sledování zásilky nebo stavu doručení je toto rozlišení důležité, protože události doručení mohou dorazit vícekrát, v nesprávném pořadí nebo být znovu přehrány po selhání sítě. Úkolem koncového bodu nemusí být dokončit každou obchodní operaci před odesláním odpovědi. Jeho prvním úkolem je spolehlivě rozhodnout, zda byla událost přijata.

Smlouva o odpovědi v praxi

Odpověď webhooku má dvě cílové skupiny: odesílající systém a vaši vlastní aplikaci. Odesílatel potřebuje jasný výsledek HTTP, aby mohl rozhodnout, zda doručení označí jako úspěšné, zopakuje ho, nebo zastaví. Vaše aplikace potřebuje dostatek času k ověření a trvalému zaznamenání události. Tyto cíle se snadněji splní, když má koncový bod krátkou synchronní část a samostatnou asynchronní část zpracování.

  1. Přijměte požadavek HTTP přes HTTPS.
  2. Zkontrolujte podpis, přihlašovací údaje, časové razítko nebo jiné mechanismy integrity požadavku vyžadované poskytovatelem.
  3. Analyzujte a ověřte payload bez provádění pomalých následných operací.
  4. Zapište událost nebo záznam pro odstranění duplicit a referenci události do trvalého úložiště či spolehlivé fronty.
  5. Vraťte záměrnou odpověď 2xx.
  6. Asynchronně zpracujte aktualizaci sledování, upozornění zákazníka, změnu inventáře nebo jinou obchodní akci.

Odpověď by neměla tvrdit, že byla událost přijata, pokud existuje pouze v paměti procesu. Pokud aplikace ihned po vrácení úspěchu havaruje, událost, která nebyla trvale uložena, se může ztratit, zatímco odesílatel se domnívá, že doručení proběhlo úspěšně. Okamžik, kdy vracíte 2xx, by proto měl odpovídat vaší skutečné garanci trvalosti.

Jaký stavový kód by měl webhook vracet?

OdpověďVýznam pro odesílateleTypické použití webhooku
200 OKPožadavek byl přijat a úspěšně zpracován.Praktická výchozí volba po ověření a trvalém přijetí.
202 AcceptedPožadavek byl přijat ke zpracování, ale práce může pokračovat.Užitečné, když byla událost bezpečně zařazena do fronty, ale obchodní zpracování probíhá asynchronně.
204 No ContentPožadavek byl úspěšný a tělo odpovědi není potřeba.Vhodné, pokud poskytovatel přijímá prázdnou úspěšnou odpověď.
400–499Požadavek je neplatný, neoprávněný nebo v odeslané podobě nepřijatelný.Poškozený payload, neúspěšné ověření, neplatný podpis nebo trvale odmítnutá událost.
429 Too Many RequestsPříjemce uplatňuje omezení rychlosti.Používejte pouze tehdy, když jsou chování odesílatele při opakování a vaše zásady omezení rychlosti kompatibilní.
500–599Příjemce nemohl požadavek přijmout kvůli problému na straně serveru nebo dočasnému problému.Nedostupná databáze, selhání fronty, selhání závislosti nebo neočekávaná chyba aplikace.

200 OK je často nejméně překvapivou volbou, protože je obecně chápán jako úspěšné přijetí. 202 Accepted je také sémanticky užitečný, když koncový bod přijal událost k pozdějšímu zpracování. Žádný z těchto kódů není automaticky správný: dokumentace odesílatele může určovat, které odpovědi 2xx se považují za úspěšné, a někteří poskytovatelé mohou vyžadovat konkrétní tělo nebo typ obsahu.

Nevracejte odpověď 2xx jen proto, že požadavek HTTP dorazil na váš server. Pokud ověření podpisu selže nebo payload nelze bezpečně interpretovat, je odpověď 4xx obvykle pravdivější. Naopak nevracejte 4xx kvůli dočasnému výpadku databáze, pokud by událost mohla později uspět. Odpověď 5xx dává odesílateli schopnému opakování možnost doručit událost znovu, ačkoli poskytovatel může uplatnit vlastní zásady.

Jak řešit timeouty?

Hodnoty timeoutů webhooku jsou specifické pro poskytovatele. Neexistuje univerzální timeout HTTP, který používá každá platforma pro sledování, a odesílatel může přestat čekat dříve, než vaše aplikace dokončí pomalou operaci. Dokumentovaný timeout odesílatele považujte za maximální hranici, nikoli za cíl. Váš koncový bod by měl běžně odpovědět výrazně před touto hranicí.

Nejčastější chybou návrhu je provést veškerou následnou práci před potvrzením webhooku. Handler může postupně volat databázi, systém správy objednávek, službu oznámení a analytickou pipeline. Jedna pomalá závislost může způsobit, že odesílatel zaznamená timeout, i když vaše aplikace práci nakonec dokončí. Odesílatel pak může požadavek zopakovat, což vytvoří duplicitní zpracování nebo konkurenční aktualizace.

Synchronní část omezte na práci potřebnou k bezpečnému rozhodnutí o přijetí. Obvykle zahrnuje ověření požadavku, základní validaci schématu, trvalé uložení události a publikování do fronty. Nákladné obohacování, dotazy na přepravce, zasílání zpráv zákazníkům a volání API třetích stran přesuňte do workeru. Sledujte odděleně čas strávený přijetím, ověřením, uložením a potvrzením události a čas strávený jejím zpracováním.

Timeout není totéž co neúspěšná obchodní operace. Z pohledu odesílatele timeout obvykle znamená, že neobdržel použitelnou úspěšnou odpověď. Vaše služba mohla událost úspěšně uložit těsně před uzavřením připojení. Proto je idempotence a odstraňování duplicit nutné, i když se koncový bod jeví jako spolehlivý.

Co způsobuje opakování požadavků?

Odesílatel webhooku může požadavek zopakovat po chybě připojení, timeoutu nebo odpovědi, kterou jeho smluvní podmínky označují jako neúspěšnou. Přesný plán, maximální počet pokusů, algoritmus prodlev a časové okno doručení se u jednotlivých poskytovatelů liší. Neslibujte pevný počet opakování, pokud není uveden v dokumentaci poskytovatele.

Příjemce by měl předpokládat, že k opakováním může docházet, a záměrně se na ně připravit:

  • Pokud je k dispozici, používejte identifikátor události. Ukládejte jej s jedinečným omezením nebo ekvivalentním klíčem pro odstranění duplicit.
  • Zajistěte idempotentní zpracování. Dvojí použití stejné aktualizace stavu doručení by nemělo odeslat dvě zprávy zákazníkovi, vytvořit dvě refundace ani nesprávně posunout objednávku.
  • Uchovávejte původní payload nebo užitečný auditní záznam. To podporuje opakované přehrání, vyšetřování a odsouhlasení.
  • Oddělte přijetí od zpracování. Worker může opakovat interní selhání, aniž by nutil odesílatele opakovat celou výměnu HTTP.
  • Zaznamenávejte stavové kódy odpovědí a latenci. Nárůst odpovědí 5xx, timeoutů nebo duplicitních ID událostí může odhalit výpadek dříve, než uživatelé nahlásí chybějící aktualizace sledování.

Duplicitní událost by měla obvykle obdržet úspěšnou odpověď, pokud byla původní událost již trvale přijata. Vrácení chyby pro každou duplicitu může vyvolat zbytečná opakování. Koncový bod může zaznamenat, že událost již byla přijata, přeskočit opakovanou obchodní akci a vrátit stejnou třídu úspěchu jako u nově přijaté události.

Kdy vracet 4xx, 429 nebo 5xx?

Vraťte 4xx, když opakování stejného požadavku pravděpodobně problém nevyřeší. Patří sem neplatný podpis, chybějící povinné ověření, nepodporovaný tvar payloadu nebo požadavek porušující trvalé validační pravidlo. Před volbou 4xx ověřte, zda odesílatel tento stav považuje za trvalé selhání. Některé platformy mají vlastní pravidla pro neúspěšná doručení.

429 používejte opatrně. HTTP definuje 429 pro omezení rychlosti a hlavička Retry-After může sdělit, kdy může být opakování vhodné. Ne každý odesílatel webhooku však interpretuje 429 stejným způsobem. Pokud je vaše fronta plná nebo je služba přetížená, ověřte, zda poskytovatel bezpečně zopakuje požadavek a zda jeho plán opakování přetížení nezhorší. Omezená vstupní fronta a plán řízení zpětného tlaku jsou obvykle lepší než nepředvídatelné selhávání požadavků.

Vraťte 5xx, když příjemce nemůže kvůli dočasnému problému událost bezpečně přijmout. Patří sem nedostupná databáze, selhání zápisu do trvalé fronty nebo interní chyba, která zabránila ověření či uložení. Vrácení 200 při tichém zahození události ztěžuje obnovu, protože odesílatel nemá důvod pokus opakovat.

Nespoléhejte při doručování webhooků na přesměrování, jako jsou 301, 302 nebo 307. Zpracování přesměrování se u klientů liší a přesměrování podepsaného požadavku může způsobit nejasnosti ohledně cíle, metody a těla. Nakonfigurujte poskytovatele přímo s finálním koncovým bodem HTTPS.

Spolehlivá zásada odpovědí pro události sledování

Pro většinu integrací webhooků pro sledování je rozumným výchozím bodem následující zásada:

  1. Vraťte 200 nebo 202 poté, co událost prošla ověřením a byla trvale uložena nebo umístěna do spolehlivé fronty.
  2. Vraťte odpověď 4xx pro neplatný podpis, neplatné ověření nebo trvale nepoužitelný payload podle dokumentovaných pravidel poskytovatele.
  3. Vraťte 5xx, pokud dočasné selhání zabrání trvalému přijetí.
  4. U bezpečně rozpoznané duplicity vraťte úspěšnou odpověď a zabraňte duplicitním obchodním účinkům.
  5. Udržujte handler rychlý a měřte latenci potvrzení.
  6. Před spuštěním do produkce testujte scénáře timeoutu, opakování, duplicit, nesprávného pořadí, poškozených požadavků a výpadku poskytovatele.

Pokud integrujete sledovací API, začněte dokumentací webhooku poskytovatele a ověřte podporované úspěšné kódy, způsob podepisování požadavků, timeout, spouštěče opakování, schéma payloadu a identifikátor události. U integrací 17TRACK je vhodným místem pro ověření smluvních podmínek poskytovatele oficiální dokumentace Tracking API, nikoli odvozování pravidel z obecné praxe HTTP.

Kontrolní seznam implementace

  • Koncový bod je dostupný přes HTTPS a má stabilní produkční URL.
  • Ověření a kontrola podpisu proběhnou před obchodním zpracováním.
  • Původní požadavek nebo ověřitelná reprezentace je uchována tam, kde je to nutné pro kontrolu podpisu a řešení problémů.
  • Událost je uložena před odesláním úspěšné odpovědi.
  • Duplicitní doručení jsou bezpečná a neopakují nevratné akce.
  • Workeři mohou opakovat interní zpracování nezávisle na cyklu opakování HTTP odesílatele.
  • Protokoly obsahují ID události, čas doručení, kód odpovědi, stav zpracování a ID korelace, aniž by odhalovaly tajné údaje.
  • Upozornění rozlišují timeouty koncového bodu, validační selhání 4xx, výpadky 5xx, zpoždění fronty a duplicitní doručení.
  • Dokumentované chování poskytovatele bylo otestováno na skutečných nebo sandboxových událostech.

Časté dotazy

Je 200 OK pro webhook lepší než 202 Accepted?

Ani jeden není univerzálně lepší. Použijte 200 OK, když byl požadavek přijat a vaše integrace považuje odpověď za obecný úspěch. Použijte 202 Accepted, když byla událost přijata k asynchronnímu zpracování. Ověřte, že odesílatel zvolenou odpověď 2xx klasifikuje jako úspěšnou.

Má koncový bod webhooku čekat, dokud nebude aktualizace sledování plně zpracována?

Obvykle ne. Měl by čekat pouze do ověření, validace a trvalého přijetí události. Dlouhotrvající práce by měla běžně proběhnout až po potvrzení, aby pomalá závislost nezpůsobila zbytečný timeout a opakování.

Co se má stát, když stejná událost sledování dorazí dvakrát?

Rozpoznejte ji pomocí ID události poskytovatele nebo pečlivě navrženého ekvivalentního klíče, přeskočte duplicitní vedlejší účinky a vraťte úspěšnou odpověď, pokud byla událost již přijata. Díky tomu jsou opakování bezpečná, aniž by se skryla nová selhání zpracování.

Má neplatný podpis vracet 400 nebo 401?

Volba závisí na vašem modelu ověřování a dokumentovaných očekáváních poskytovatele. Oba kódy mohou vyjádřit odmítnutí, ale důležitější než univerzální výběr jednoho z nich je konzistence. Událost nepotvrzujte, pokud nemůžete ověřit její pravost.

Způsobí odpověď 5xx vždy opakování?

Ne. Mnoho webhookových systémů opakuje timeouty a chyby serveru, ale spouštěče a plány opakování jsou specifické pro poskytovatele. Považujte opakování za dokumentované chování integrace a ověřte je v testovacím prostředí.

Zdroje