Webhooky
Webhooky umožňují zasílání informací o nějaké události, která v systému nastane, např. vytvoření nebo editace objednávky. Systém při každé z těchto událostí pošle HTTP požadavek na URL adresu nastavenou ve webhooku.
Vytvoření a správa webhooku
Správa webhooků (vytvoření, editace, smazání) je možná pouze přes API. Více najdete v dokumentaci k Webhook API.
Každý webhook vytvořený v systému je vázán na uživatele API, který ho vytvořil. Pokud tento uživatel nemá práva např. na endpoint objednávek, nepůjde mu vytvořit ani webhook na události spojené s objednávkami. Stejně to funguje i pro jiné typy webhooků. Pokud uživatel má webhook vytvořen a jsou mu změněna oprávnění, webhook se deaktivuje.
Volání webhooku
URL adresa nastavená ve webhooku se volá jako POST požadavek, v těle požadavku je JSON, jehož obsahem je seznam identifikátorů entit ze systému (např. objednávek).
Bližší popis je u každého typu webhooku.
POST požadavek na URL adresu nastavenou ve webhooku bude očekávat odpověď 200 OK nebo 204 No Content.
Spojení se navazuje s timeoutem 1 vteřina, na celkové vyřízení požadavku (včetně přenosu odpovědi) má váš server 3 vteřiny.
Tzn. ve vyřízení požadavku na straně serveru volaného webhookem by se neměla data přímo zpracovávat, pouze si data uložit a vrátit příslušný stavový kód co nejdříve, ideálně pod 1 vteřinu.
V případě špatné odpovědi (nebo nedostupnosti cílového serveru) bude systém odesílat webhook každých 5 minut až do chvíle, než obdrží správnou odpověď. Stejný 5minutový cyklus a stejný mechanismus platí pro všechny typy událostí bez rozdílu - webhook nemá žádnou prioritní frontu např. pro Orders.create oproti ostatním eventům.
Pokud webhook dostane kladnou odpověď, nebo přesáhne výše zmíněný 3vteřinový timeout na vyřízení požadavku, bude se brát jako úspěšně doručený a nebude se provádět opakované volání - i když žádná odpověď fakticky nedorazila. Toto chování je záměrné (server, který nestihne odpovědět v limitu, se nepenalizuje jako chybový), ale má důsledek pro sledování doručitelnosti: pole last_success_call_status/last_error_call v Webhook API se v tomto případě nastaví jako u skutečně úspěšného volání (last_success_call_status: 200), takže nejsou spolehlivým indikátorem, že vaše aplikace odpověď skutečně přijala a zpracovala. Pokud potřebujete přesně sledovat doručení, musí váš endpoint vždy odpovědět dostatečně rychle a spolehlivě evidovat přijaté volání na své straně.
Webhooky se odesílají z IP adresy serveru projektu. Tu je možné zjistit v Nastavení / Domény a SSL.
Webhooky se odesílají v maximálně 5000 položek v jednom požadavku.
Vždy se odesílá poslední dostupná úprava položky (např. produktu) i pokud je položka upravena vícekrát rychle za sebou. Ve webhooku se neodesílají položky duplicitně.
Webhooky se odesílají v pořadí create, update, delete.
Atribut project_name v požadavku - jedná se o unikátní název projektu, který si zvolíte při založení nového projektu. Název je neměnný a vždy se bude odesílat stejná hodnota pro daný projekt.
Informace o stavu webhooku, posledním úspěšném nebo neuspěšném volání najdete v Webhook API
Testování
Webhooky je možné spustit akcemi v administraci nebo přes API. Např. vytvořením, změnou nebo smazáním produktu.