Slovník pojmů

Webhook

Webhook šetří pravidelné dotazování. Není ale zárukou jediného ani seřazeného doručení události.

Stručná definice

Událost přichází k příjemci, místo aby si ji sám vyžádal.

Při pollingu se klient opakovaně ptá API, zda se něco změnilo. U webhooku poskytovatel pošle HTTP požadavek na předem zaregistrovanou callback URL příjemce — například když platební brána potvrdí platbu nebo dopravce změní stav zásilky.

Webhook není dlouhodobé spojení ani přesně jednou doručená zpráva. Poskytovatel má vlastní pravidla pro formát payloadu, timeout, podpis, opakování a ruční redelivery. Příjemce proto nesmí měnit objednávku jen proto, že mu přišel libovolný JSON na veřejný endpoint.

Použití

Kde webhook dává smysl

Vhodný je pro oznámení změny, na kterou má jiný systém reagovat bez zbytečného čekání.

potvrzení, zamítnutí nebo vrácení platby
nová objednávka z marketplace a změny jejího stavu
předání informace o zásilce nebo jejím doručení
oznámení dokončeného importu, buildu či jiné asynchronní úlohy
spuštění následné synchronizace, zatímco zdrojové API zůstává autoritou dat

Praktický příklad

Změna stavu zásilky od dopravce

Dopravce odešle událost shipment.delivered s ID doručení a číslem zásilky. Endpoint nad původním tělem ověří podpis a timestamp, pak v jedné transakci uloží ID události s unikátním omezením a zařadí změnu do fronty. Teprve potom vrátí 204.

Worker dohledá objednávku podle čísla zásilky, ověří, že nová změna dává vzhledem k aktuálnímu stavu smysl, a zapíše ji. Druhé doručení stejné události je bezpečně potvrzeno, ale nevytvoří druhou změnu ani neposílá další e-mail.

Jak funguje

Bezpečný příjem události v pěti krocích

Příjem má být rychlý, dohledatelný a oddělený od pomalé obchodní práce.

Odeslání události Poskytovatel sestaví payload, ID události, timestamp a podle svého protokolu podpis.
Převzetí raw body Endpoint čte původní bajty těla a hlavičky dříve, než data dekóduje nebo přeformátuje.
Ověření pravosti Ověří podpis podle dokumentace poskytovatele, v konstantním čase, a případně přiměřené stáří timestampu.
Trvalé přijetí V transakci uloží ID doručení a vytvoří job či záznam pro další práci; unikátní constraint brání souběžné duplicitě.
Rychlé potvrzení Vrátí očekávané 2xx a vlastní import provede asynchronně a idempotentně.

Důležité pojmy

Pravost, opakování a stav události

Jednotlivé ochrany mají jiný účel. Žádná z nich sama nepokryje celý tok.

HMAC podpis

HMAC nad daty přesně určenými poskytovatelem — často raw payloadem a timestampem — dokládá, že zprávu vytvořil držitel tajemství a tělo nebylo změněno. Nezaručuje důvěrnost dat ani nenahrazuje HTTPS.

Timestamp a replay

Dříve platnou podepsanou zprávu může útočník zkusit přehrát. Kontrola krátkého časového okna, event ID a trvalá deduplikace společně omezují replay i běžné retry.

Event ID a business identita

ID doručení chrání před druhým zpracováním stejné zprávy. Pro objednávku nebo platbu je vhodná i idempotence podle externí business identity.

Timeout a redelivery

Pomalá odpověď nebo výpadek může vyvolat další doručení. HTTP 200 či 204 potvrzuje přijetí požadavku, nikoli dokončení celého importu.

Vztah k podobným pojmům

Webhook je aktivní oznámení, ne náhrada všech API volání.

Často funguje spolu s API a frontou, přesto každá část řeší jinou odpovědnost.

API a polling: API si klient volá sám. Webhook oznamuje změnu, ale příjemce si podle potřeby přes API ověří aktuální stav.
Fronta zpráv: Webhook dorazí po HTTP zvenčí. Fronta může uvnitř systému oddělit jeho přijetí od vlastního zpracování.
Retry: Poskytovatel může zkusit doručení znovu. Příjemce proto odpovídá rychle a zvládá duplicitní eventy.
JWT: Někteří poskytovatelé používají tokeny, jiní HMAC. Formát JWT není obecnou náhradou ověření specifikovaného pro daný webhook.

Výhody a omezení

Rychlejší reakce, ale více odpovědnosti na straně příjemce.

Přínosy

méně zbytečného pollingu a rychlejší informace o změně
retry může řešit krátký výpadek příjemce
oddělení HTTP příjmu od pomalého importu či volání další služby
dohledatelná evidence konkrétní události

Časté chyby

přijmout payload bez ověření podpisu a timestampu
ověřovat podpis nad znovu serializovaným JSONem
vracet 2xx před trvalým uložením události
předpokládat jediné či správně seřazené doručení
držet staré secret bez řízené rotace

Hranice použití

Webhook má oznamovat změnu, ne nést celý synchronní proces.

Endpoint by neměl během jedné HTTP odpovědi volat několik externích služeb, generovat dokumenty a čekat na dlouhý import. Hrozí timeout, opakované doručení i špatně dohledatelný výsledek. Rozumnější je po ověření bezpečně přijmout událost a předat ji workeru.

Zdrojový systém může být nadále zdrojem pravdy. Když události přijdou mimo pořadí nebo mají nejasný význam, worker si vyžádá aktuální stav přes API. To je lepší než odvozovat stav objednávky pouze z pořadí notifikací.

Na co myslet

Webhookový endpoint patří mezi bezpečnostní hranice systému.

Pravidla podpisu, tolerance času a chování při chybě se musí řídit dokumentací konkrétního poskytovatele.

HTTPS, bezpečné uložení a rotace secrets bez jejich logování
raw body, očekávaný algoritmus a constant-time porovnání podpisu
event ID a databázová ochrana proti duplicitě
rychlé 2xx až po trvalém přijetí zprávy
korelační ID, historie doručení a řízené ruční opakování

Časté otázky

Co webhook nezaručuje

Je webhook totéž co REST API?

Ne. Webhook je poskytovatelem iniciované HTTP oznámení události. REST API obvykle popisuje klientem iniciovanou práci se zdroji.

Stačí ověřit HMAC podpis?

Ne. Je potřeba HTTPS, správně použitý raw payload, constant-time porovnání, případně timestamp a vždy deduplikace doručení.

Mám vrátit 2xx až po dokončení importu?

Obvykle ne. Po ověření a trvalém přijetí je lepší potvrdit doručení rychle; businessovou práci zpracovat odděleně.

Může webhook přijít vícekrát nebo mimo pořadí?

Ano. Retry, timeout a ruční redelivery jsou běžné. Příjemce musí zpracování navrhnout idempotentně a stav podle potřeby ověřit u zdroje.

Jak navrhuji integrační toky v praxi

Přijetí události odděluji od jejího bezpečného dokončení.

U objednávek, skladů a externích služeb řeším kontrakt, validaci, duplicitní doručení, retry i dohledatelné chybové stavy.

Jak pracuji s API a integracemi Nezávazně probrat projekt