Webhooky v ecommerce — praktické využití

Webhook je obyčejný HTTP požadavek, který vám jiný systém pošle ve chvíli, kdy se něco stane. Vznikne objednávka, zaplatí se, změní se sklad. Místo abyste se každou minutu ptali „je něco nového?“, dozvíte se to hned.

V ecommerce jsou webhooky páteří většiny rychlých integrací. Zároveň jsou nejčastějším místem, kde se integrace tiše rozbije. V článku ukážeme, k čemu je v e-shopu používáme, jak je přijímat bezpečně a na co pamatovat, aby se žádná událost neztratila.

Jak webhook funguje

Princip je jednoduchý. V e-shopu nebo platební bráně zaregistrujete URL a vyberete události, které vás zajímají. Když událost nastane, platforma pošle na vaši URL požadavek s popisem události. Váš server odpoví kódem 200 a tím potvrdí převzetí.

Obsah notifikace se liší. Některé platformy posílají celý objekt, jiné jen „oznámení o změně“:

• Shoptet posílá standardně jen metadata: ID e-shopu, typ události, čas a identifikátor entity. Detail si aplikace dotáhne přes API. U podporovaných událostí lze nově zapnout i plná data entity přímo v notifikaci (k 9/2026, u produktových webhooků jde podle Shoptetu o betu).
• GoPay posílá na notification_url jen ID platby. Stav platby si e-shop musí ověřit dotazem na API.
• Shopify, WooCommerce a Stripe posílají v těle přímo data objektu nebo události.

Tenká notifikace s dotažením přes API má výhodu. Vždy pracujete s aktuálním stavem, ne se starou kopií.

Praktická využití v e-shopu

Na tabulce je vidět hlavní přínos. Webhook spojuje systémy, které spolu jinak nemluví: e-shop, ERP, sklad, CRM, marketplace, e-mailing. Kde vznikne víc takových vazeb, vyplatí se je vést přes middleware, aby každá událost nešla do pěti systémů zvlášť.

Pro jednodušší toky stačí nástroj typu n8n. Webhook spustí scénář a ten třeba založí úkol nebo pošle zprávu do Slacku. U objednávek, plateb a skladu stavíme robustnější řešení s frontou.

Pravidlo č. 1: odpovězte rychle, zpracujte později

Platformy čekají na odpověď jen krátce. Shoptet vyžaduje potvrzení kódem 200 do 4 sekund, jinak notifikaci pošle znovu. Shopify doporučuje odpovědět do 5 sekund (k 9/2026). Kdo v obsluze webhooku zapisuje do ERP, generuje PDF a posílá e-maily, limit snadno překročí.

Správný postup:

1. Přijmout požadavek.
2. Ověřit podpis.
3. Uložit událost do fronty zpráv nebo databáze.
4. Odpovědět 200.
5. Samotné zpracování nechat workerům na pozadí.

Pozor i na opačnou chybu. Shoptet v dokumentaci upozorňuje, že když skript odpoví chybou (například 500 nebo 422), notifikace přijde znovu. Odpověď 200 tedy posílejte až po bezpečném uložení, ale před náročným zpracováním.

Pravidlo č. 2: ověřte podpis

URL webhooku je veřejná. Kdokoliv, kdo ji zná, na ni může poslat podvrženou „zaplacenou objednávku“. Proto všechny velké platformy požadavky podepisují:

Nejčastější chyba při ověřování: framework tělo požadavku nejdřív rozparsuje jako JSON a podpis se pak počítá z přeformátovaného textu. Shopify výslovně upozorňuje, že podpis se musí počítat ze surového těla, tedy ještě před body parserem. Další chyby jsou porovnání podpisů obyčejným == místo porovnání v konstantním čase a zapomenutý secret u WooCommerce, kde je nepovinný.

U tenkých notifikací typu GoPay je druhou pojistkou samotný princip. Nevěříte obsahu notifikace, ale stav platby si ověříte dotazem na API brány. Víc o zabezpečení píšeme v článku Bezpečnost API integrací.

Pravidlo č. 3: počítejte s duplicitami a výpadky

Webhooky mají dvě nepříjemné vlastnosti. Mohou přijít víckrát. A mohou nepřijít vůbec.

Duplicity. Shopify v dokumentaci uvádí, že stejný webhook můžete dostat opakovaně, a doporučuje idempotentní zpracování. Prakticky: každou událost identifikujte (Shopify k tomu posílá hlavičku X-Shopify-Webhook-Id), uložte si zpracovaná ID a opakování přeskočte. Objednávka se pak do ERP nezapíše dvakrát.

Výpadky. Opakované doručení má každá platforma jinak nastavené (k 9/2026):

• Shoptet: po 15 minutách, celkem nejvýš tři pokusy.
• Shopify: až 8 opakování během 4 hodin, při trvalých chybách odběr zruší.
• WooCommerce: po pěti neúspěšných doručeních po sobě webhook vypne. Znovu ho musíte zapnout ručně.
• Stripe: v ostrém režimu až tři dny s rostoucím odstupem.

Hodinový výpadek serveru tak na Shoptetu znamená ztracené události. Proto webhooky vždy doplňujeme kontrolní úlohou, která pravidelně porovná stav přes API. Shopify to ve své dokumentaci doporučuje přímo. Rozdíl mezi událostmi a dávkami rozebíráme v článku Cron joby vs. realtime.

Pořadí. Události nemusí dorazit ve stejném pořadí, v jakém vznikly. Pokud přijde „objednávka zaplacena“ dřív než „objednávka vytvořena“, zpracování musí umět počkat, nebo si aktuální stav dotáhnout z API.

Monitoring: jak poznat, že webhooky nechodí

Nejhorší selhání webhooku je tiché. Nic nespadne, jen přestanou chodit data. Hlídáme proto:

• čas poslední přijaté události pro každý typ (když v pracovní den hodinu nepřišla žádná objednávka, je to podezřelé),
• velikost fronty a počet neúspěšných zpracování,
• stav odběrů na straně platformy. Shoptet má endpoint GET /api/webhooks/notifications s logem notifikací, včetně počtu opakování a stavu,
• počet rozdílů, které najde kontrolní úloha. Když roste, webhooky někde vypadávají.

Podrobný postup je v článku Monitoring integrací.

Jak na to prakticky: checklist příjmu webhooků

• Endpoint běží na HTTPS a odpovídá do pár sekund.
• Podpis se ověřuje ze surového těla a porovnává v konstantním čase.
• Událost se uloží dřív, než se odpoví 200.
• Zpracování běží asynchronně s opakováním při chybě.
• Každá událost má ID a duplicity se přeskakují.
• Kontrolní úloha přes API dorovnává ztracené události.
• Existuje alert na výpadek příjmu i na plnou frontu.
• U WooCommerce někdo hlídá, jestli se webhook nevypnul.

Pokud některý bod chybí, integrace možná funguje, ale jen do prvního výpadku. Příjem webhooků, fronty a kontrolní úlohy stavíme v rámci integrací a u složitějších řešení jako samostatné API a mikroslužby. Pošlete nám, které systémy potřebujete propojit, a navrhneme, jak události tokem vést, aby se neztrácely.