Webhook prijmite cez HTTPS, overte podpis nad pôvodným telom a čas správy, validujte schému a udalosť uložte s jedinečným ID. Odpovedzte rýchlo a spracujte ju vo fronte idempotentne. Počítajte s duplicitou a zmeneným poradím, monitorujte chyby a periodicky zosúlaďujte kritické dáta.
Webhook je správa, ktorou jeden systém oznámi druhému udalosť, napríklad prijatú platbu, zmenu zásielky alebo nový kontakt. Oproti pravidelnému zisťovaniu stavu dokáže reagovať rýchlo a s menším počtom požiadaviek. Doručenie cez internet však nie je dokonale usporiadaný rad: správa môže prísť viackrát, neskoro, súbežne alebo vôbec. Prijímateľ musí s týmito vlastnosťami počítať.
Bezpečný endpoint tiež nemôže veriť ľubovoľnému JSON iba preto, že vyzerá správne. Overuje pôvod, integritu, čas, formát a oprávnenie udalosti. Spracovanie oddeľuje rýchle prijatie od pomalej biznis práce a udržiava pozorovateľnosť. Nasledujúci návrh je použiteľný pre WordPress, WooCommerce aj samostatnú aplikáciu.
Definujte kontrakt a životný cyklus udalosti
Dokumentujte typy udalostí, verziu, jedinečné ID, čas vzniku, identitu objektu a schému dát. Rozlíšte, či payload (telo správy) obsahuje úplný aktuálny objekt alebo iba oznámenie, po ktorom treba zavolať API. Pri úplnom objekte môže oneskorená staršia udalosť prepísať novší stav; pri následnom API volaní zase treba zvládnuť limit a nedostupnosť. Výber závisí od poskytovateľa a požadovanej konzistencie.
Udalosti majú stav prijatá, overená, čakajúca, spracovaná alebo chybná. Uložte pôvodné telo primerane citlivosti a dobu uchovania obmedzte. Jedinečné ID chráni pred duplicitou, korelačné ID spája následné kroky. Definujte finálne a prechodné stavy biznis objektu, aby oneskorená správa „platba čaká“ nevrátila už zaplatenú objednávku späť.
Overte podpis a zabráňte opakovanému zneužitiu
Podpis overujte presne podľa dokumentácie poskytovateľa, zvyčajne nad neupraveným telom požiadavky a časovou značkou. Ak framework telo najprv preformátuje, výsledný podpis sa môže líšiť. Porovnanie robte bezpečným spôsobom a neplatnú správu odmietnite pred biznis spracovaním. Tajomstvo ukladajte v bezpečnej konfigurácii, používajte samostatné hodnoty pre prostredia a pripravte rotáciu.
Časové okno a evidencia ID znižujú riziko opätovného prehrania zachytenej platnej správy. IP allowlist môže byť doplnková vrstva, ak poskytovateľ publikuje stabilné rozsahy, nie jediný dôkaz pôvodu. Endpoint obmedzte veľkosťou tela, podporovanými metódami a rýchlostným limitom. Chybové odpovede nezverejňujú stack trace ani tajomstvá. Pri vlastnom odosielateľovi chráňte rovnakým spôsobom prijímateľa aj podpisovací kľúč.
- HTTPS a podpis nad pôvodným telom
- Časová tolerancia a jedinečné ID
- Oddelené tajomstvá a plán rotácie
- Limit veľkosti, metódy a frekvencie
Odpovedzte rýchlo a spracujte vo fronte
Endpoint má overiť a trvalo uložiť udalosť, potom rýchlo vrátiť úspech. Ak počas jednej požiadavky generuje dokument, volá tri API a posiela e-mail, poskytovateľ môže vyhodnotiť timeout a udalosť zopakovať. Front oddeľuje prijatie od práce, umožňuje obmedziť súbeh a zachová správu počas dočasného výpadku závislosti. Potvrdenie však posielajte až po bezpečnom uložení, nie pred ním.
Worker používa idempotentnú operáciu a kontroluje aktuálny stav objektu. Dočasnú chybu opakuje s rastúcim odstupom, trvalú chybu schémy alebo oprávnenia presunie do karantény. Počet pokusov a vek udalosti majú limit. Administrácia alebo dashboard umožní opravenú správu bezpečne zopakovať bez ručnej zmeny databázy. Pri prísnom poradí spracujte udalosti podľa objektu sekvenčne alebo použite verziu stavu.
Pri odosielaní rešpektujte prijímateľa
Vlastný webhook odosielajte s jasnou dokumentáciou, verziou a podpisom. Prijímateľský endpoint validujte pri registrácii a citlivú zmenu adresy potvrďte. Nastavte timeout, obmedzený počet pokusov a exponenciálny odstup s rozptylom. Úspech definujte podľa dohodnutého rozsahu stavových kódov. Trvalú klientsku chybu neopakujte donekonečna, no sprístupnite dôvod vlastníkovi integrácie.
Každý odberateľ má vlastné tajomstvo a možnosť pozastavenia bez vplyvu na ostatných. Logujte ID udalosti, cieľ, pokus, čas a bezpečný výsledok. Payload minimalizujte a citlivé údaje radšej sprístupnite autentifikovaným následným API volaním, ak to model umožňuje. Pri zmene schémy pridajte verziu a prechodné obdobie; tichá nekompatibilita je nebezpečnejšia než explicitne odmietnutá nová verzia.
- Samostatné tajomstvo pre každého príjemcu
- Timeout a kontrolované opakovanie
- Verzovaný payload s minimom dát
- Možnosť pozastavenia a opätovného doručenia
Testujte a zosúlaďujte kritické dáta
Testy pokrývajú platný a neplatný podpis, starú časovú značku, duplicitu, súbeh, zmenené poradie, poškodený JSON, timeout a chybu závislosti. Vývojárom poskytnite bezpečný spôsob opakovania testovacej udalosti a ukážkové payloady bez produkčných osobných údajov. Pri lokálnom tuneli dbajte na prístup a po teste ho vypnite. Záťažová skúška preverí front aj ochranu endpointu.
Monitoring sleduje mieru prijatia, overenia, spracovania, počet opakovaní, vek frontu a karanténu. Kritické údaje pravidelne zosúlaďujte cez API alebo export, pretože webhook nemusí byť jedinou pravdou. Ak sa rozdiel nájde, proces ho opraví alebo predloží človeku. Runbook vysvetlí, kde nájsť udalosť, ako overiť stav u poskytovateľa a kedy je bezpečné opakovanie.
Časté otázky
Aký je rozdiel medzi API a webhookom?
API sa zvyčajne volá, keď chce klient údaje alebo akciu; webhook iniciuje poskytovateľ pri udalosti. Často sa kombinujú: webhook upozorní na zmenu a prijímateľ si cez API načíta overený aktuálny stav.
Prečo webhook prišiel dvakrát?
Poskytovateľ môže opakovať doručenie po timeoute alebo chýbajúcom potvrdení a sieť nevie garantovať presne jeden pokus. Prijímateľ musí používať ID udalosti a idempotentné spracovanie, nie predpokladať jediné doručenie.
Má endpoint vždy vrátiť úspech?
Nie. Neplatný podpis alebo schému treba odmietnuť primeraným stavom. Pri platnej udalosti potvrďte až bezpečné uloženie. Konkrétna odpoveď a pravidlá opakovania sa riadia dokumentáciou poskytovateľa a vaším kontraktom.
Zdroje a ďalšie čítanie
Web developer zo Spišskej Novej Vsi. Venuje sa WordPressu, WooCommerce, vlastným pluginom, API integráciám, webovým aplikáciám a praktickým AI automatizáciám.
