Webhooks: čo to je, ako fungujú a kedy ich použiť

Webhook je mechanizmus na doručovanie udalostí medzi systémami v reálnom čase. Namiesto toho, aby prijímací systém pravidelne kontroloval (polling), či sa niečo stalo, odosielateľ (provider) pošle HTTP požiadavku (spravidla POST) na prednastavenú adresu (endpoint) príjemcu vždy, keď nastane konkrétna udalosť — napríklad vykonaná platba, zmena stavu objednávky, príchod nového komentára alebo úspešné dokončenie build procesu.

Ako to funguje v praxi: poskytovateľ služby vám umožní zaregistrovať URL, kam má posielať notifikácie. Keď sa stane sledovaná udalosť, server poskytovateľa vytvorí HTTP požiadavku so štruktúrovaným telom (často JSON) a odošle ju na vašu URL. Vaša aplikácia na tejto URL spracuje prijatú informáciu a vráti odpoveď (zvyčajne HTTP 200). To je celé — jednoduché a efektívne.

Rozdiel medzi webhookom a bežným API/pollingom

• Polling: klient pravidelne posiela dotazy na server, či niečo nové je. Nevýhodou sú zbytočné požiadavky, vyššia latencia medzi udalosťou a oznámením a vyššie zaťaženie.
• Webhook: server aktivne notifikáciu odošle ihneď po udalosti. Výhodou sú nízka latencia a menšia záťaž. Na druhej strane treba riešiť bezpečnosť, spoľahlivosť prijímacieho endpointu a správne spracovanie prijatých správ.

Typické formáty a údaje

Webhooks zvyčajne používajú JSON v tele HTTP POST požiadavky. Okrem dát o udalosti obsahujú aj hlavičky s metaúdajmi (napr. typ udalosti, čas, identifikátor). Niektorí poskytovatelia posielajú aj podpísané hlavičky (HMAC), ktoré umožňujú overiť integritu a pôvod požiadavky.

Bezpečnosť a overovanie

Pretože endpoint je verejne prístupný, je dôležité zabrániť zneužitiu:

• HTTPS: vždy používať TLS, aby sa zabránilo odpočúvaniu.
• Sekret v URL nie je ideálny: lepšie je mať pevne definovanú URL a overovať podpis v hlavičke.
• HMAC podpis: poskytovateľ sa so spotrebiteľom dohodne na tajnom kľúči; pri každej správe server vytvorí HMAC (napr. SHA256) a pošle ho v hlavičke. Príjemca vypočíta HMAC z prijatého tela a porovná ho.
• IP allowlist: ak to umožňuje poskytovateľ, obmedzte prístup len na známe IP adresy.
• Rate limiting: chráňte svoj endpoint proti zahlteniu.

Spoľahlivosť a idempotencia

Systémy môžu mať sieťové chyby; preto väčšina poskytovateľov podporuje opakované pokusy (retries) pri neúspechu. To znamená, že príjemca môže dostať rovnakú udalosť viackrát. Preto treba:

• Implementovať idempotentné spracovanie: používať unikátny identifikátor udalosti, uložiť, že už bola spracovaná, a pri duplicitnom doručení ignorovať opätovné vykonanie vedľajších efektov.
• Rýchle odpovede: endpoint by mal čo najrýchlejšie vrátiť potvrdenie (200 OK). Ak je potrebné vykonať zdĺhavé operácie, odporúča sa prijaté dáta rýchlo zaevidovať a spracovať asynchrónne (napr. cez frontu).

Praktické odporúčania pri implementácii

• Validácia: kontrolujte štruktúru a podpis, aby ste sa vyhli falošným udalosťam.
• Logovanie: zapisujte prijaté udalosti, odpovede a chyby — uľahčí to debugging.
• Časové limity: nastavte rozumné timeouty (napr. 5–10 s), aby sa poskytovateľ môhol rozhodnúť o retry.
• Status kódy: používajte správne HTTP statusy. 2xx = úspech, 4xx = chyba klienta (napr. neoprávnený prístup), 5xx = chyba servera.
• Testovanie: využite nástroje ako ngrok (tunelovanie lokálneho servera), RequestBin alebo webhook.site na zachytávanie a ladenie udalostí.

Bežné použitia webhooks

• E‑commerce: notifikácie o zaplatení, zmene stavu objednávky, vrátení peňazí.
• CI/CD: Git služby (GitHub, GitLab) posielajú push alebo merge udalosti, ktoré spúšťajú buildy.
• Chat a notifikácie: integrácie s chatovacími platformami pri nových správach alebo udalostiach.
• Monitoring a alerty: systémy upozornia externé služby pri detekcii incidentu.
• IoT: zariadenia alebo brány informujú backend o udalostiach v reálnom čase.

Časté problémy a riešenia

• Straty notifikácií: nastavte retries a uložte udalosti v poradí, aby ste zvládli dočasné zlyhania.
• Duplicitné spracovanie: používať idempotentné operácie a evidenciu spracovaných eventov.
• Nečitateľné payloady: dohodnite sa na schéme JSON alebo použite verzovanie (event_version) tak, aby zmeny neporušili staršie integrácie.
• Škálovanie: ak očakávate veľký počet udalostí, pridajte frontu (message queue) medzi prijímačom a spracovaním.

Praktický príklad toku: platobná brána

Platobná brána po úspešnom zaplatení odošle webhook s informáciami o transakcii. Vaše API overí podpis, skontroluje identifikátor transakcie, uloží stav do databázy a vráti 200. Ak vaše spracovanie zahŕňa napr. vystavenie účtenky, toto môže bežať asynchrónne cez job queue.

Zhrnutie

Webhooks sú jednoduchý, efektívny a často používaný spôsob, ako dosiahnuť notifikácie v reálnom čase medzi systémami bez neustáleho pollingu. Kľúčové pri ich používaní je myslieť na bezpečnosť, spoľahlivosť a idempotentné spracovanie. Dobre navrhnutý webhook endpoint dokáže výrazne zjednodušiť integrácie a znížiť latenciu pri prenose udalostí medzi službami.