Webhook přijímejte přes HTTPS, ověřte podpis nad původním tělem i čas zprávy, validujte schéma a událost uložte s jedinečným ID. Odpovězte rychle a zpracujte ji ve frontě idempotentně. Počítejte s duplicitami a změněným pořadím, monitorujte chyby a kritická data pravidelně slaďujte.
Webhook je zpráva, kterou jeden systém oznámí druhému událost, například přijatou platbu, změnu zásilky nebo nový kontakt. Oproti pravidelnému zjišťování stavu dokáže reagovat rychle a s menším počtem požadavků. Doručení přes internet však není dokonale uspořádaná řada: zpráva může přijít vícekrát, pozdě, souběžně nebo vůbec. Příjemce musí s těmito vlastnostmi počítat.
Bezpečný endpoint také nemůže věřit libovolnému JSON jen proto, že vypadá správně. Ověřuje původ, integritu, čas, formát a oprávnění události. Zpracování odděluje rychlé přijetí od pomalé byznysové práce a zachovává pozorovatelnost. Následující návrh je použitelný pro WordPress, WooCommerce i samostatnou aplikaci.
Definujte kontrakt a životní cyklus události
Dokumentujte typy událostí, verzi, jedinečné ID, čas vzniku, identitu objektu a schéma dat. Rozlište, zda payload (tělo zprávy) obsahuje úplný aktuální objekt, nebo pouze oznámení, po kterém je třeba zavolat API. U úplného objektu může opožděná starší událost přepsat novější stav; při následném volání API je zase nutné zvládnout limity a nedostupnost. Volba závisí na poskytovateli a požadované konzistenci.
Události mají stav přijatá, ověřená, čekající, zpracovaná nebo chybná. Původní tělo uložte přiměřeně jeho citlivosti a dobu uchování omezte. Jedinečné ID chrání před duplicitou, korelační ID propojuje následné kroky. Definujte finální a přechodné stavy business objektu, aby opožděná zpráva „platba čeká“ nevrátila již zaplacenou objednávku zpět.
Ověřte podpis a zabraňte opakovanému zneužití
Podpis ověřujte přesně podle dokumentace poskytovatele, obvykle nad neupraveným tělem požadavku a časovou značkou. Pokud framework tělo nejprve přeformátuje, výsledný podpis se může lišit. Porovnání provádějte bezpečným způsobem a neplatnou zprávu odmítněte před business zpracováním. Tajný klíč ukládejte v bezpečné konfiguraci, používejte samostatné hodnoty pro jednotlivá prostředí a připravte rotaci.
Časové okno a evidence ID snižují riziko opětovného přehrání zachycené platné zprávy. IP allowlist může být doplňkovou vrstvou, pokud poskytovatel publikuje stabilní rozsahy, nikoli jediným důkazem původu. Endpoint omezte velikostí těla, podporovanými metodami a rychlostním limitem. Chybové odpovědi nezveřejňují stack trace ani tajemství. U vlastního odesílatele chraňte stejným způsobem příjemce i podpisový klíč.
- HTTPS a podpis nad původním tělem
- Časová tolerance a jedinečné ID
- Oddělené tajné klíče a plán rotace
- Limit velikosti, metody a frekvence
Odpovězte rychle a zpracujte ve frontě
Endpoint má ověřit a trvale uložit událost a poté rychle vrátit úspěch. Pokud během jednoho požadavku generuje dokument, volá tři API a posílá e-mail, poskytovatel může vyhodnotit timeout a událost zopakovat. Fronta odděluje přijetí od práce, umožňuje omezit souběh a zachová zprávu během dočasného výpadku závislosti. Potvrzení však posílejte až po bezpečném uložení, ne před ním.
Worker používá idempotentní operaci a kontroluje aktuální stav objektu. Dočasnou chybu opakuje s rostoucím odstupem, trvalou chybu schématu nebo oprávnění přesune do karantény. Počet pokusů a stáří události mají limit. Administrace nebo dashboard umožní opravenou zprávu bezpečně zopakovat bez ruční změny databáze. Při striktním pořadí zpracujte události pro daný objekt sekvenčně, nebo použijte verzi stavu.
Při odesílání respektujte příjemce
Vlastní webhook odesílejte s jasnou dokumentací, verzí a podpisem. Přijímající endpoint validujte při registraci a citlivou změnu adresy potvrďte. Nastavte timeout, omezený počet pokusů a exponenciální odstup s rozptylem. Úspěch definujte podle dohodnutého rozsahu stavových kódů. Trvalou chybu klienta neopakujte donekonečna, ale zpřístupněte důvod vlastníkovi integrace.
Každý odběratel má vlastní tajemství a možnost pozastavení bez vlivu na ostatní. Logujte ID události, cíl, pokus, čas a bezpečný výsledek. Payload minimalizujte a citlivé údaje raději zpřístupněte autentizovaným následným voláním API, pokud to model umožňuje. Při změně schématu přidejte verzi a přechodné období; tichá nekompatibilita je nebezpečnější než explicitně odmítnutá nová verze.
- Samostatné tajemství pro každého příjemce
- Timeout a řízené opakování
- Verzovaný payload s minimem dat
- Možnost pozastavení a opětovného doručení
Testujte a slaďujte kritická data
Testy pokrývají platný a neplatný podpis, starou časovou značku, duplicitu, souběh, změněné pořadí, poškozený JSON, timeout a chybu závislosti. Vývojářům poskytněte bezpečný způsob opakování testovací události a ukázkové payloady bez produkčních osobních údajů. U lokálního tunelu dbejte na přístup a po testu jej vypněte. Zátěžová zkouška prověří frontu i ochranu endpointu.
Monitoring sleduje míru přijetí, ověření, zpracování, počet opakování, stáří fronty a karanténu. Kritická data pravidelně sesouhlasujte přes API nebo export, protože webhook nemusí být jediným zdrojem pravdy. Pokud se najde rozdíl, proces ho opraví nebo předloží člověku. Runbook vysvětlí, kde najít událost, jak ověřit stav u poskytovatele a kdy je opakování bezpečné.
Časté dotazy
Jaký je rozdíl mezi API a webhookem?
API se obvykle volá, když klient chce data nebo akci; webhook iniciuje poskytovatel při události. Často se kombinují: webhook upozorní na změnu a příjemce si přes API načte ověřený aktuální stav.
Proč webhook přišel dvakrát?
Poskytovatel může doručení zopakovat po timeoutu nebo chybějícím potvrzení a síť nedokáže zaručit právě jeden pokus. Příjemce musí používat ID události a idempotentní zpracování, nikoli předpokládat jediné doručení.
Má endpoint vždy vrátit úspěch?
Ne. Neplatný podpis nebo schéma je třeba odmítnout přiměřeným stavem. U platné události potvrďte až bezpečné uložení. Konkrétní odpověď a pravidla opakování se řídí dokumentací poskytovatele a vaším kontraktem.
Zdroje a další čtení
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
