vebhukTakéHTTP callback, Web hookPokročilý
Definice
Webhook je způsob, jak aplikace automaticky oznámí jiné aplikaci událost pomocí HTTP požadavku na předem zadanou adresu. Místo průběžného dotazování odešle zdrojový systém zprávu ve chvíli, kdy se něco stane, například po zaplacení objednávky, změně stavu úlohy nebo vytvoření záznamu.
Proč webhook nahrazuje dotazování
Webhook řeší situaci, kdy jeden systém potřebuje rychle zjistit, že se v jiném systému stala událost. Bez webhooku by klient často volal API ve smyčce a ptal se, jestli už je platba hotová, soubor zpracovaný nebo ticket uzavřený. Webhook obrací směr komunikace: zdroj události pošle zprávu příjemci sám, jakmile má co oznámit.
Webhook proto šetří požadavky, zkracuje zpoždění a zjednodušuje integrace mezi službami. Typický příjemce je veřejná HTTPS adresa v aplikaci, integrační platformě nebo serverless funkci. Typický odesílatel je platební služba, Git hosting, CRM, e-shop, monitoring nebo nástroj pro automatizaci.
Co přesně putuje přes HTTP
Webhook bývá obyčejný HTTP POST na předem nakonfigurovaný endpoint. Tělo požadavku nejčastěji obsahuje JSON s typem události, identifikátorem objektu, časem vzniku a daty, která příjemce potřebuje pro další krok. Hlavičky často nesou podpis, verzi schématu, identifikátor doručení nebo informaci o opakovaném pokusu.
Webhook není samostatný internetový protokol. Webhook je vzor použití HTTP pro doručování událostí mezi aplikacemi. Rozdíl proti běžnému volání API je v iniciátorovi: u API si klient aktivně žádá data, zatímco u webhooku zdrojová služba aktivně oznamuje změnu.
Spolehlivost: duplicitní zprávy, pořadí a opakování
Webhookové doručování se v praxi navrhuje jako nejistá síťová komunikace. Odesílatel nemusí vědět, jestli příjemce zprávu zpracoval, pokud odpověď nedorazí včas. Mnoho služeb proto po chybě nebo timeoutu požadavek zopakuje. Příjemce musí počítat s duplicitami a zpracovávat události idempotentně, například podle unikátního ID doručení.
Webhook také nemusí dorazit ve stejném pořadí, v jakém události vznikly. Bezpečný návrh často uloží událost do fronty, rychle vrátí úspěšný HTTP status a těžší práci provede asynchronně. U plateb se proto stav objednávky typicky nemění jen podle jedné zprávy, ale ověřuje se i vůči zdrojovému systému nebo událostní historii.
Ověření odesílatele a bezpečný příjem
Webhook endpoint je často dostupný z internetu, takže příjemce nesmí věřit jen tomu, že požadavek přišel na správnou URL. Běžná ochrana používá HTTPS, tajný podpis přes HMAC, časové razítko, kontrolu opakování a omezené ukládání citlivých dat. U služeb jako platební brána je ověření podpisu kritické, protože falešná událost by mohla označit objednávku jako zaplacenou.
Webhook by měl vracet pouze nezbytnou odpověď a neměl by spouštět dlouhé synchronní procesy. Pomalý endpoint vyvolává opakované doručování, hromadění požadavků a obtížné ladění. U opakované platby může špatně ošetřená duplicita znamenat dvojí e-mail, chybnou účetní akci nebo nekonzistentní stav předplatného.
Příklady z praxe
Potvrzení zaplacené objednávky
E-shop pošle zákazníka na platební stránku a nečeká otevřeným spojením na výsledek platby. Platební služba po úspěšné autorizaci zavolá webhook e-shopu s událostí payment.succeeded. E-shop ověří podpis, uloží ID události kvůli duplicitám a teprve potom označí objednávku jako zaplacenou.
const crypto = require("node:crypto"); app.post("/webhooks/payment", express.raw({ type: "application/json" }), (req, res) => { const signature = req.get("x-signature") || ""; const expected = crypto .createHmac("sha256", process.env.WEBHOOK_SECRET) .update(req.body) .digest("hex"); if (signature !== expected) return res.sendStatus(401); const event = JSON.parse(req.body.toString("utf8")); if (event.type === "payment.succeeded") { markOrderAsPaid(event.data.orderId); } res.sendStatus(204); });Dokončení asynchronního zpracování videa
Služba pro zpracování videa přijme soubor a několik minut vytváří náhledy v různých rozlišeních. Backend aplikace místo opakovaného dotazování čeká na webhook video.processing.finished. Po doručení zprávy aktualizuje stav videa v databázi a pošle uživateli notifikaci, že soubor je připravený k publikaci.
Časté omyly
- MýtusWebhook je jen jiné slovo pro API endpoint.
- Ve skutečnostiWebhook sice často míří na API endpoint, ale označuje hlavně událostní způsob komunikace. Rozhodující je, že požadavek iniciuje zdroj události, ne klient, který se ptá na data.
- MýtusKdyž webhook vrátí 200, je všechno bezpečně hotové.
- Ve skutečnostiÚspěšný HTTP status říká hlavně to, že příjemce požadavek přijal. Skutečné zpracování může probíhat později ve frontě a aplikace musí řešit duplicity, selhání navazujících kroků i konzistenci stavu.
- MýtusTajná URL webhooku stačí jako zabezpečení.
- Ve skutečnostiTajná URL je slabá obrana, protože adresa se může objevit v logu, konfiguraci nebo chybové zprávě. Bezpečnější návrh ověřuje podpis požadavku a odmítá zprávy s neplatným nebo příliš starým časovým razítkem.
Časté dotazy
- Musí být webhook endpoint veřejně dostupný?
- Webhook endpoint má být veřejně dostupná HTTPS adresa, kterou dokáže zavolat odesílající služba. Lokální adresa typu localhost nestačí, protože existuje jen na vývojářově počítači. Při vývoji se často používá dočasný tunelovací nástroj nebo testovací prostředí nasazené na internetu. Produkční endpoint by měl mít stabilní URL, platný TLS certifikát, rychlou odpověď a ověření podpisu požadavku.
- Kdy dává webhook větší smysl než polling?
- Webhook je vhodnější než pravidelné dotazování, když zdrojová služba umí událost sama oznámit a příjemce nepotřebuje znát stav každých pár sekund bez změny. Polling může být jednodušší u systémů, které webhooky nepodporují, nebo tam, kde stačí občasná synchronizace. Webhook snižuje počet zbytečných požadavků, ale přidává potřebu řešit podpisy, opakované doručení a veřejný příjem požadavků.
- Jak poznám, že webhook opravdu poslala správná služba?
- Webhook by neměl spoléhat na tajnost URL jako hlavní ochranu. Bez ověření může kdokoli, kdo adresu zjistí nebo odhadne, poslat podobně vypadající požadavek. Bezpečnější příjem používá kryptografický podpis těla požadavku, časové razítko a kontrolu opakovaného doručení. Omezení podle IP adresy může pomoci, ale samo o sobě bývá křehké, protože poskytovatelé mohou infrastrukturu měnit.
- Co se stane, když příjemce webhooku zrovna nefunguje?
- Webhook se při výpadku příjemce obvykle nedoručí hned, ale mnoho poskytovatelů zkusí doručení opakovat podle vlastních pravidel. Příjemce musí být připraven na to, že některé události dorazí pozdě, víckrát nebo v jiném pořadí. Robustní aplikace uloží ID události, kontroluje aktuální stav objektu u zdroje a má ruční nebo automatický způsob, jak chybějící události doplnit.
Zdroje
- HTTP Semantics(otevře se v novém okně)
- Webhooks(otevře se v novém okně)
- Webhook event delivery(otevře se v novém okně)
- HTTP(otevře se v novém okně)
- OWASP API Security Project(otevře se v novém okně)
Související pojmy
