Spoľahlivé webhooky: ako zabrániť dvojitému spracovaniu udalostí

Objednávkový systém dostane oznámenie, že sa zmenil stav platby. Spracuje ho, no odpoveď sa cestou stratí. Keď rovnaké oznámenie príde znova, môže nekvalitná integrácia vytvoriť druhú úlohu pre sklad. Toto je modelový scenár, nie príbeh konkrétneho zákazníka.

Webhook je oznámenie, ktoré jedna služba posiela na pripravenú adresu druhej aplikácie pri určitej udalosti. Umožňuje systémom reagovať bez neustáleho pýtania sa na zmeny. Spoľahlivosť však nevznikne iba tým, že endpoint vráti HTTP 200. Treba rozlišovať pravosť správy, prijatie a dokončenie obchodnej operácie.

Doručenie správy nie je dokončená objednávka

HTTP odpoveď potvrdzuje výsledok požiadavky podľa zmluvy konkrétneho poskytovateľa. Pri asynchrónnom návrhu môže byť správa bezpečne prijatá, zatiaľ čo vlastná práca čaká vo fronte. Firma preto potrebuje dva pohľady: či oznámenie dorazilo a či sa požadovaný úkon skutočne vykonal.

Vlastný návrh integrácie by mal pomenovať prijaté, spracúvané, dokončené a chybové položky. Tieto stavy sú návrhová pomôcka, nie povinné názvy rozhrania Stripe či GitHub. Dôležité je, aby podpora vedela vysvetliť, prečo objednávka stojí, a bezpečne pokračovať.

Najprv overte odosielateľa

GitHub odporúča HTTPS a webhook secret. Pri konkrétnej integrácii použite overenie podpisu presne podľa poskytovateľa. Znalosť verejnej URL nie je dôkaz oprávneného odosielateľa. Tajomstvo nepatrí do URL, bežného logu ani ukážky pre zákazníka.

Pri Stripe webhookoch treba na overenie podpisu zachovať pôvodné telo požiadavky. Svojvoľná úprava JSON pred kontrolou môže overenie pokaziť. To však neznamená, že treba surové telá neobmedzene archivovať v aplikačných logoch. Prístup a dobu uchovania navrhnite podľa potreby integrácie.

Overenie podpisu nerieši všetko: nasleduje kontrola typu udalosti a toho, či ju aplikácia vôbec podporuje. Pred zavedením nového typu je vhodné mať test očakávaného aj neznámeho obsahu. Neznáme pole nemusí byť útok, ale nesmie potichu spustiť nepovolený obchodný úkon.

Jedna udalosť môže prísť viackrát

Stripe výslovne upozorňuje na duplicity a negarantované poradie doručenia. Nie je správne odvodiť z toho identické správanie každého poskytovateľa. Každá integrácia má vlastné pravidlá opakovania a obnovy po zlyhaní, ktoré treba overiť v dokumentácii.

Idempotentné spracovanie znamená, že opakovanie tej istej zamýšľanej operácie nevytvorí ďalší neželaný účinok. Nestačí urobiť otázku „existuje už ID?“ a až potom bez ochrany zapisovať. Dve súbežné požiadavky môžu obe dostať odpoveď nie. Z tohto dôvodu navrhujeme databázovú jedinečnosť spolu s transakčným spracovaním.

Identita udalosti a identita obchodného úkonu sú pritom rozdielne. Dve odlišné udalosti môžu smerovať k tej istej objednávke. Okrem deduplikácie doručenia preto treba pravidlo, ktorý prechod stavu objednávky je prípustný. Staršia správa nemá bez kontroly prepísať novší potvrdený stav.

Model dvoch doručení a jedného výsledku

Predstavme si syntetickú udalosť s označením event-demo-001. Príde dvakrát. Nasledujúci návrh je vysvetľujúci postup, nie kód na nasadenie a nie skutočný formát udalosti poskytovateľa:

1. Overiť podpis, typ a základné údaje.
2. Trvalo uložiť prijatú položku s jedinečným kľúčom z poskytovateľa, účtu a ID udalosti.
3. Potvrdiť prijatie až po bezpečnom uložení. Opakované doručenie nesmie vytvoriť druhú prijatú položku.
4. Spracovať položku na pozadí a obchodnú zmenu chrániť pred súbehom aj opakovaním.
5. Zaznamenať výsledok a umožniť kontrolované opakovanie po chybe.

Ak proces spadne po prijatí a pred spracovaním, trvalo uložená položka musí zostať dohľadateľná. Samotný záznam „ID sme už videli“ nestačí, ak sa práca nikdy nedokončila. Pri odosielaní ďalšej požiadavky do externého systému sa navyše musí riešiť aj opakovanie na tejto hranici.

Idempotency key pre odchádzajúce Stripe API požiadavky je iný nástroj než evidencia prijatých webhookov. Jedno automaticky nenahrádza druhé. Podobne vzor Competing Consumers vysvetľuje potrebu zohľadniť idempotenciu pri práci s frontami.

Praktická preberacia skúška integrácie

Pred odovzdaním pošlite v testovacom prostredí tú istú syntetickú udalosť dvakrát aj súbežne. Potom simulujte chybu pracovníka fronty a obnovte spracovanie. Nakoniec zmeňte poradie súvisiacich udalostí. Očakávaný obchodný výsledok musí byť vopred popísaný, inak sa úspech nedá vyhodnotiť.

Do protokolu zapíšte identifikátory testov, stavy a výsledky bez tajomstiev a nepotrebných osobných údajov. Zelená odpoveď endpointu nie je dostatočné kritérium. Test má ukázať aj to, či sa problém dostane k človeku, ktorý vie konať.

Čo má obsahovať zadanie dodávateľovi

Žiadajte popis podpisovania, duplicít, obnovy po zlyhaní a monitoringu nedokončených udalostí. Určite vlastníka prevádzky a spôsob bezpečného opakovania. Pri vývoji aplikácií a API integrácií môže Yenwa začať kontrolou jednej kritickej udalosti od prijatia až po výsledok v cieľovom systéme.