Čo je webhook? Ako si aplikácie navzájom posielajú správy

Webhook je automatická správa, ktorú jedna služba pošle vašej aplikácii v momente, keď sa niečo stane. Keď sa zaplatí zákazníkova platba, Stripe pošle webhook na adresu vo vašej aplikácii s informáciou „platba prebehla, tu sú podrobnosti“ a vaša aplikácia na to zareaguje — označí objednávku ako zaplatenú, pošle potvrdenie, odomkne účet. Stručne: API je situácia, keď sa vaša aplikácia pýta inej služby na otázku; webhook je situácia, keď druhá služba volá vašu aplikáciu, aby jej niečo povedala.

Prečo na tom záleží pri tvorbe s AI

Hneď ako vaša aplikácia prijíma platby, spracúva odoslané formuláre z iného nástroja alebo sa pripája k službám ako GitHub, Shopify alebo kalendár, stretnete sa s webhookmi. Sú zvyčajne správnym spôsobom, ako zistiť, že sa niečo stalo — no práve tu sú aplikácie vytvorené s AI najčastejšie jemne nesprávne:

• Koncový bod prijme akúkoľvek požiadavku, takže ktokoľvek môže sfalšovať udalosť „platba prebehla“.
• Aplikácia udelí prístup na stránke presmerovania po platbe namiesto vo webhooku, takže ľudia, ktorí zavrú kartu predčasne, nikdy nedostanú, čo zaplatili, a ľudia, ktorí nájdu URL úspešnej platby, to dostanú zadarmo.
• Tá istá udalosť príde dvakrát a zákazník dostane dve objednávky alebo dva e-maily.

Keď viete, ako webhooky fungujú, môžete si ochranu vyžiadať od začiatku.

Každodenné prirovnanie: textová správa o doručení

Dozvedieť sa, či vám dorazila zásielka, môžete dvoma spôsobmi. Môžete každých desať minút chodiť k predným dverám a kontrolovať to (to je polling — vaša aplikácia opakovane volá API s otázkou „je niečo nové?“). Alebo vám kuriér pošle SMS, keď zásielku doručí (to je webhook).

SMS je jasne lepšia — pokiaľ jej môžete dôverovať. Ak by vám mohol ktokoľvek poslať správu „zásielka doručená“, chceli by ste nejaký spôsob, ako zistiť, že naozaj prišla od kuriéra. A ak bol váš telefón vypnutý, keď prišla správa, chceli by ste, aby sa kuriér pokúsil doručiť neskôr znovu. Tieto dve veci — overenie a opakovania — tvoria väčšinu toho, čo robí webhooky náročnými.

Ako webhook funguje krok za krokom

1. Vytvoríte koncový bod vo svojom backende: URL ako https://yourapp.com/webhooks/stripe, ktorá prijíma požiadavky POST.
2. Zaregistrujete túto URL u poskytovateľa a vyberiete, ktoré udalosti chcete (napríklad „checkout dokončený“ a „predplatné zrušené“).
3. Poskytovateľ vám dá podpisové tajomstvo. Uložíte ho ako tajomstvo na svojom serveri — pozri premenné prostredia a tajomstvá.
4. Nastane udalosť. Poskytovateľ pošle HTTP požiadavku na vašu URL s JSON telom, ktoré ju opisuje, plus hlavičku s podpisom.
5. Vaša aplikácia overí podpis, zaznamená ID udalosti, rýchlo odpovie úspešným kódom (200) a až potom vykoná prácu.
6. Ak vaša aplikácia neodpovie úspešne, mnohí poskytovatelia to skúsia znovu neskôr.

Podpisy

Podpis dokazuje, že požiadavka prišla od poskytovateľa a nebola zmenená. Stripe napríklad vypočíta HMAC (druh fingerprintu s kľúčom) s SHA-256 nad telom požiadavky a časovou pečiatkou, pomocou podpisového tajomstva, a pošle ho v hlavičke Stripe-Signature. Vaša aplikácia urobí rovnaký výpočet so svojou kópiou tajomstva; ak sa výsledky zhodujú, požiadavka je pravá. Keďže je podpísaná aj časová pečiatka, môžete odmietnuť staré požiadavky, ktoré niekto zaznamenal a pustil neskôr — knižnice Stripe majú predvolene päťminútovú toleranciu podľa jeho dokumentácie k septembru 2026.

Jeden praktický detail: podpis sa počíta nad surovým telom požiadavky. Ak váš framework pred overením JSON spracuje a znovu naformátuje, kontrola zlyhá. Je to veľmi častá chyba.

Opakovania, duplicity a poradie

Poskytovatelia sa líšia, preto si skontrolujte dokumentáciu každého z nich. K septembru 2026:

Dokumentácia Stripe tiež uvádza, že udalosti nie sú zaručene doručené v poradí, v akom sa stali, a že tá istá udalosť môže občas prísť viackrát, preto odporúča sledovať ID udalostí.

Všeobecné ponaučenie platí pre každého poskytovateľa: udalosti môžu prísť neskoro, viackrát a v inom poradí. Vaše spracovanie má byť idempotentné — spracovanie tej istej udalosti dvakrát má rovnaký účinok ako jedno spracovanie.

Praktický príklad: odomknutie plateného kurzu

Predávate online kurz. Študent klikne na Kúpiť, zaplatí na hostovanej platobnej stránke Stripe a je presmerovaný späť na váš web.

Krehký spôsob: stránka „ďakujeme“ odomkne kurz. Ak študent počas presmerovania zavrie prehliadač, zaplatil, ale nemá prístup. Ak niekto uhádne URL stránky ďakujeme, dostane prístup bez platby.

Spôsob cez webhook:

1. Keď Stripe potvrdí platbu, pošle udalosť checkout.session.completed na /webhooks/stripe.
2. Váš backend overí podpis podpisovým tajomstvom. Ak zlyhá, odpovie 400 a nič neurobí.
3. Skontroluje, či už bolo ID tejto udalosti spracované. Ak áno, odpovie 200 a skončí.
4. Uloží ID udalosti, odpovie 200 a potom udelí študentovi prístup a pošle uvítací e-mail.
5. Stránka ďakujeme len hovorí „Platba prijatá — váš kurz sa zobrazí o chvíľu“ a kontroluje stav prístupu študenta.

Neskôr, ak sa predplatné zruší alebo karta zlyhá, ďalšie udalosti webhooku povedia vašej aplikácii, aby prístup odobrala alebo pozastavila. Takto sa predplatné produkty držia v súlade s fakturáciou — pozri čo je SaaS a ako pridať platby do aplikácie.

Kľúčové pojmy

• Koncový bod: URL vo vašej aplikácii, ktorá prijíma webhooky.
• Udalosť / payload: čo sa stalo a dáta, ktoré to opisujú (zvyčajne JSON).
• Podpisové tajomstvo: zdieľané tajomstvo na overenie podpisov.
• Idempotentné: bezpečné spustiť viackrát s rovnakým výsledkom.
• Polling: opakované pýtanie sa API na zmeny namiesto čakania na webhook.
• Tunel: nástroj, ktorý dá notebooku dočasnú verejnú URL, aby webhooky mohli počas vývoja doraziť.

Časté chyby a mylné predstavy

• Neoverovanie podpisov. URL koncového bodu nie je tajomstvo. Práve overenie robí požiadavku dôveryhodnou.
• Pomalá práca pred odpoveďou. Odosielanie e-mailov alebo generovanie PDF pred odpoveďou môže spôsobiť timeouty, čo vyvolá opakovania, čo vytvorí duplicity.
• Predpoklad presne raz a v poradí. Zaznamenávajte ID udalostí a nespoliehajte sa na poradie doručenia.
• Použitie URL náhľadu. Webhooky potrebujú stabilnú verejnú adresu. Súkromné náhľady a localhost nie sú dostupné z internetu; použite svoju publikovanú URL (alebo tunel počas testovania).
• Miešanie testovacích a živých tajomstiev. Poskytovatelia často vydávajú rozdielne podpisové tajomstvá pre testovací a živý režim. Uložte obe a používajte správnu.
• Slepá dôvera obsahu pri dôležitých rozhodnutiach. Pri akciách s vysokou dôležitosťou je rozumné po prijatí udalosti načítať najnovší stav z API poskytovateľa.

Čo požiadať od svojho AI tvorcu

Pridaj na serveri koncový bod POST /webhooks/stripe. Over podpis Stripe pomocou surového tela požiadavky a tajomstva STRIPE_WEBHOOK_SECRET. Neplatné podpisy odmietni s kódom 400. Ulož ID každej udalosti a preskoč udalosti, ktoré už boli spracované. Rýchlo odpovedz 200 a potom spracuj checkout.session.completed označením objednávky ako zaplatenej a odoslaním potvrdenia. Zaznamenaj typ udalosti. Prístup neudeľuj na stránke úspešnej platby.

Potom ho otestujte: pošlite testovaciu udalosť z dashboardu poskytovateľa, pošlite tú istú znovu a pošlite požiadavku s nesprávnym podpisom. Zmenu by mala spraviť len prvá.

Webhooky v Mythex

Mythex nemá samostatnú službu pre webhooky; požiadate agenta, aby pridal koncový bod webhooku do vlastného backendu vašej aplikácie, a poskytovateľovi nastavíte publikovanú URL, pretože webhooky potrebujú verejnú adresu. Podpisové tajomstvo patrí do tajomstiev projektu a ak ho zmeníte na živej aplikácii, znovu publikujte. Dokumentačný recept o spracovaní webhookov obsahuje štartovací prompt a šablóny obchodov sú dobrým východiskom pre aplikácie, ktoré prijímajú platby.

Otázky