Co je webhook? Jak si aplikace posílají zprávy

Webhook je automatická zpráva, kterou jedna služba pošle vaší aplikaci v okamžiku, kdy se něco stane. Když zákazníkova platba projde, Stripe pošle webhook na adresu ve vaší aplikaci se zprávou „platba proběhla, tady jsou podrobnosti“ a vaše aplikace na to zareaguje — označí objednávku jako zaplacenou, odešle účtenku, odemkne účet. Stručně: API je situace, kdy se vaše aplikace na něco zeptá jiné služby; webhook je situace, kdy vám druhá služba volá a něco sděluje.

Proč je to důležité při tvorbě s AI

Jakmile vaše aplikace přijímá platby, zpracovává formuláře z jiného nástroje nebo se napojuje na služby jako GitHub, Shopify nebo kalendář, na webhooky narazíte. Obvykle jsou to správný způsob, jak zjistit, že se něco stalo, ale právě tady bývají aplikace vytvořené s AI nenápadně špatně:

• Koncový bod přijme jakýkoli požadavek, takže kdokoli může podvrhnout událost „platba proběhla“.
• Aplikace uděluje přístup na přesměrovací stránce po platbě místo ve webhooku, takže lidé, kteří zavřou okno brzy, nedostanou, co zaplatili, a lidé, kteří najdou adresu úspěchu, to dostanou zdarma.
• Stejná událost dorazí dvakrát a zákazník dostane dvě objednávky nebo dva e-maily.

Kdo ví, jak webhooky fungují, může si ochranu vyžádat hned na začátku.

Analogie: textová zpráva o doručení

Zásilku můžete zjistit dvěma způsoby. Můžete každých deset minut chodit ke dveřím a kontrolovat ji (tomu se říká polling — vaše aplikace opakovaně volá API a ptá se „je něco nového?“). Nebo vám kurýr pošle SMS, že je doručeno (to je webhook).

SMS je jasně lepší — pokud jí můžete věřit. Kdyby kdokoli mohl posílat zprávu „zásilka doručena“, chtěli byste mít způsob, jak ověřit, že přišla opravdu od kurýra. A když byl váš telefon vypnutý, až SMS přišla, chtěli byste, aby se kurýr pokusil doručit znovu později. Tyto dvě věci — ověření a opakování — tvoří většinu obtížnosti webhooků.

Jak webhook funguje krok za krokem

1. Vytvoříte koncový bod v backendu vaší aplikace: URL, například https://yourapp.com/webhooks/stripe, která přijímá požadavky POST.
2. Tuto URL zaregistrujete u poskytovatele a vyberete události, které chcete (například „checkout dokončen“ a „předplatné zrušeno“).
3. Poskytovatel vám dá podepisovací tajný klíč. Uložíte ho jako tajný klíč na serveru — viz proměnné prostředí a tajné klíče.
4. Nastane událost. Poskytovatel odešle HTTP požadavek na vaši URL s tělem JSON, které ji popisuje, a s hlavičkou podpisu.
5. Vaše aplikace ověří podpis, zaznamená ID události, rychle odpoví úspěšným kódem (200) a teprve potom provede práci.
6. Pokud vaše aplikace neodpoví úspěchem, mnoho poskytovatelů to zkusí později znovu.

Podpisy

Podpis dokazuje, že požadavek přišel od poskytovatele a nebyl změněn. Stripe například spočítá HMAC (druh klíčovaného otisku) s SHA-256 nad tělem požadavku a časovým razítkem, a to pomocí podepisovacího tajného klíče, a odešle ho v hlavičce Stripe-Signature. Vaše aplikace provede stejný výpočet se svou kopií tajného klíče; když se výsledky shodují, požadavek je pravý. Protože je časové razítko také podepsané, můžete odmítnout staré požadavky, které si někdo zaznamenal a přehrává později — knihovny Stripe mají podle jeho dokumentace k září 2026 výchozí toleranci pět minut.

Jeden praktický detail: podpis se počítá nad surovým tělem požadavku. Pokud váš framework JSON před ověřením zpracuje a znovu naformátuje, kontrola selže. Je to velmi častá chyba.

Opakování, duplicity a pořadí

Poskytovatelé se liší, zkontrolujte dokumentaci každého z nich. K září 2026:

Dokumentace Stripe také uvádí, že události nejsou zaručeně doručeny v pořadí, v jakém se staly, a že stejná událost se občas může doručit více než jednou, proto doporučuje sledovat ID událostí.

Obecné ponaučení platí u každého poskytovatele: události mohou dorazit opožděně, vícekrát a v jiném pořadí. Vaše obsluha má být idempotentní — zpracování stejné události dvakrát má stejný účinek jako zpracování jednou.

Příklad: odemčení placeného kurzu

Prodáváte online kurz. Student klikne na Koupit, zaplatí na hostované pokladně Stripe a je poslán zpět na váš web.

Křehký způsob: stránka „Děkujeme“ odemkne kurz. Pokud student během přesměrování zavře prohlížeč, zaplatil, ale přístup nemá. Pokud někdo uhodne URL stránky „Děkujeme“, přístup získá bez platby.

Způsob přes webhook:

1. Když Stripe platbu potvrdí, pošle událost checkout.session.completed na /webhooks/stripe.
2. Váš backend ověří podpis pomocí podepisovacího tajného klíče. Pokud selže, odpoví 400 a nic neudělá.
3. Zkontroluje, zda už toto ID události bylo zpracováno. Pokud ano, odpoví 200 a skončí.
4. Uloží ID události, odpoví 200 a teprve potom studentovi udělí přístup a odešle uvítací e-mail.
5. Stránka „Děkujeme“ jen říká „Platba přijata — váš kurz se za chvíli objeví“ a kontroluje stav přístupu studenta.

Později, když se předplatné zruší nebo karta selže, další události webhooků řeknou vaší aplikaci, aby přístup odebrala nebo pozastavila. Tak zůstávají produkty na předplatné v souladu s fakturací — viz co je SaaS a jak přidat platby do aplikace.

Klíčové pojmy

• Koncový bod (endpoint): URL ve vaší aplikaci, která přijímá webhooky.
• Událost / payload: co se stalo a data, která to popisují (obvykle JSON).
• Podepisovací tajný klíč (signing secret): sdílený tajný klíč používaný k ověření podpisů.
• Idempotentní: bezpečné spustit vícekrát se stejným výsledkem.
• Polling: opakované dotazování API na změny, místo čekání na webhook.
• Tunel: nástroj, který dá notebooku dočasnou veřejnou URL, aby na něj mohly webhooky dosáhnout během vývoje.

Běžné chyby a omyly

• Neověřování podpisů. URL koncového bodu není tajná. Ověření je to, co z požadavku dělá důvěryhodný.
• Pomalá práce před odpovědí. Odesílání e-mailů nebo generování PDF před odpovědí může vést k timeoutům, ty spustí opakování a opakování způsobí duplicity.
• Předpoklad přesně jednou a v pořadí. Zaznamenávejte ID událostí a nespoléhejte na pořadí příchodu.
• Použití URL náhledu. Webhooky potřebují stabilní veřejnou adresu. Soukromé náhledy a localhost z internetu nedosáhnou; použijte publikovanou URL (nebo tunel při testování).
• Míchání testovacích a živých tajných klíčů. Poskytovatelé často vydávají různé podepisovací klíče pro testovací a živý režim. Uložte oba a používejte správný.
• Slepé důvěřování datům z payloadu u důležitých rozhodnutí. U akcí s vysokými sázkami je rozumné po přijetí události stáhnout aktuální stav z API poskytovatele.

Co žádat od vašeho AI nástroje

Přidej na serveru koncový bod POST /webhooks/stripe. Ověř podpis Stripe pomocí surového těla požadavku a tajného klíče STRIPE_WEBHOOK_SECRET. Neplatné podpisy odmítni s 400. Ukládej každé ID události a přeskoč události, které už byly zpracovány. Rychle odpověz 200 a pak zpracuj checkout.session.completed tak, že označíš objednávku jako zaplacenou a odešleš účtenku. Zaloguj typ události. Přístup neuděluj ze stránky úspěchu pokladny.

Pak to otestujte: pošlete zkušební událost z dashboardu poskytovatele, pošlete stejnou znovu a pošlete požadavek se špatným podpisem. Jen první by něco měl změnit.

Webhooky na Mythexu

Mythex neprovozuje samostatnou službu webhooků; agenta požádáte, aby do backendu vaší aplikace přidal koncový bod pro webhook, a poskytovateli nastavíte publikovanou URL, protože webhooky potřebují veřejnou adresu. Podepisovací tajný klíč vložíte do tajných klíčů projektu a pokud ho změníte u živé aplikace, znovu publikujete. Návod v dokumentaci zpracování webhooků obsahuje výchozí prompt a šablony obchodů jsou dobrým výchozím bodem pro aplikace, které přijímají platby.

Otázky