Webhook
Také známé jako: webhook notifikace, callback, událostní notifikace
Webhook je notifikace, kterou systém sám odešle ve chvíli, kdy nastane určitá událost — vznikne objednávka, změní se produkt, aktualizuje se sklad. Nahrazuje pravidelné dotazování: místo aby se integrace ptala „změnilo se něco?", dozví se to, až když se skutečně něco stane.
Kdy webhooky použít
Všude, kde dnes běží pravidelné dotazování. Synchronizace skladu, předávání objednávek do ERP, notifikace o změně produktu. Úspora je dvojí: méně vyčerpaných limitů a data v cíli dřív.
Jak správně postavit přijímací stranu
Tohle je místo, kde se webhooky nejčastěji rozbíjejí, a pravidlo je jednoduché: přijmi, ulož, odpověz. Zpracuj potom.
Odesílající systém obvykle čeká na odpověď jen velmi krátce — u některých platforem jde o jednu vteřinu. Když se v té době pokusíš objednávku rovnou zaúčtovat, časový limit vyprší a odesílatel to vyhodnotí jako neúspěch.
Druhá věc: počítej s opakováním. Když se doručení nepovede, systém to zkusí znovu. Zpracování proto musí být napsané tak, aby dvojí doručení téže události nezaložilo dvě objednávky.
Třetí věc: notifikace obvykle nese jen identifikátory. Detaily si dotáhneš přes API — a to už bez spěchu.
Nejčastější chyby
- Synchronní zpracování v obsluze webhooku. Vyprší časový limit, odesílatel to opakuje a vzniknou duplicity.
- Nezajištěná odolnost vůči opakovanému doručení. Tatáž objednávka se zpracuje dvakrát.
- Chybějící monitoring přijímací strany. Když endpoint spadne, notifikace se ztrácejí a nikdo o tom neví.
- Ponechání pravidelného dotazování vedle webhooků. Zbytečně vyčerpává limity, které měly webhooky ušetřit.
Shoptet a Upgates
Upgates. Webhooky se spravují výhradně přes API (vytvoření, editace, smazání) a jsou vázané na konkrétního API uživatele — při změně jeho práv se webhook deaktivuje. Volání je POST na nastavenou adresu s JSON tělem obsahujícím seznam identifikátorů; očekává se 200 OK nebo 204 No Content. Časový limit je 1 vteřina — proto na straně příjemce jen uložit a vrátit kód. Při neúspěchu se opakuje každých 5 minut do úspěchu. Maximum je 5000 položek na požadavek, odesílá se poslední úprava položky, bez duplicit, v pořadí create → update → delete. (Ověř aktuální stav.)
Časté otázky
Proč se mi objednávky zpracovávají dvakrát?
Protože zpracování není odolné vůči opakovanému doručení. Systém opakuje notifikace, u kterých nedostal včasnou odpověď — a tvoje strana je bere jako nové události.
Kolik času mám na odpověď?
Velmi málo, u některých platforem jednu vteřinu. Proto se v obsluze webhooku nic nezpracovává, jen ukládá.
Nahradí webhooky pravidelné dotazování úplně?
Ve většině případů ano. Kontrolní dotazování v delším intervalu se ale hodí jako pojistka proti ztraceným notifikacím.
Související pojmy
- API – API je rozhraní, přes které spolu programy komunikují přímo, bez člověka a bez souborů. U e-shopu umožňuje číst a měnit data v reálném čase — vytvořit objednávku, upravit sklad, načíst produkty — na rozdíl od feedu, který je jednosměrný snímek.
- REST API – REST API je nejrozšířenější způsob, jak stavět webová rozhraní: každý typ dat má vlastní adresu a operace se vyjadřuje metodou HTTP požadavku. Naprostá většina e-shopových platforem nabízí právě tuhle podobu API.
- Rate limit – Rate limit je omezení počtu požadavků, které smí jedna integrace na rozhraní poslat za daný čas. Chrání server před přetížením a u e-shopových platforem bývá navázaný na tarif — takže víc integrací znamená dělit se o stejný rozpočet požadavků.
- Napojení ERP – Napojení ERP je propojení e-shopu s podnikovým systémem tak, aby si vyměňovaly data automaticky — typicky objednávky z e-shopu do ERP a sklad s cenami z ERP na e-shop. Realizuje se buď hotovým doplňkem, nebo vlastní integrací přes API.
- ERP – ERP je podnikový systém, ve kterém firma vede sklad, objednávky, fakturaci a účetnictví na jednom místě. U e-shopu bývá zdrojem pravdy o skladu a cenách, zatímco e-shop je prodejní kanál — a rozhodnutí, který systém co určuje, je základ jakéhokoli napojení.
- API klíč – API klíč je přístupový údaj, kterým se integrace prokazuje při komunikaci s rozhraním. Určuje nejen to, kdo se připojuje, ale i co smí — a proto by měl mít každé napojení vlastní klíč s minimem oprávnění.
Další pojmy ze skupiny Feedy & integrace
- APIAPI je rozhraní, přes které spolu programy komunikují přímo, bez člověka a bez souborů. U e-shopu umožňuje číst a měnit data v reálném čase — vytvořit objednávku, upravit sklad, načíst produkty — na rozdíl od feedu, který je jednosměrný snímek.
- API klíčAPI klíč je přístupový údaj, kterým se integrace prokazuje při komunikaci s rozhraním. Určuje nejen to, kdo se připojuje, ale i co smí — a proto by měl mít každé napojení vlastní klíč s minimem oprávnění.
- Datová migraceDatová migrace je převod obsahu e-shopu z jednoho systému do druhého — produktů, kategorií, zákazníků, objednávek a jejich vzájemných vazeb. Nejtěžší na ní nejsou samotná data, ale vazby mezi nimi a pole, která v cílovém systému nemají protějšek.
- Diagnostika feeduDiagnostika feedu je pravidelná kontrola toho, kolik produktů kanál z feedu skutečně přijal, kolik jich zamítl a proč. Je to jediný způsob, jak zjistit, že část sortimentu tiše vypadla — počet položek ve feedu totiž neříká nic o tom, kolik se jich reálně zobrazuje.
- ERPERP je podnikový systém, ve kterém firma vede sklad, objednávky, fakturaci a účetnictví na jednom místě. U e-shopu bývá zdrojem pravdy o skladu a cenách, zatímco e-shop je prodejní kanál — a rozhodnutí, který systém co určuje, je základ jakéhokoli napojení.
- Export produktůExport produktů je vytažení dat z katalogu do souboru nebo rozhraní pro použití jinde — pro srovnávače, pro účetnictví, pro dodavatele nebo jako záloha před hromadnou úpravou. Na rozdíl od feedu nemusí mít pevnou strukturu danou cizím systémem.