Přejít na hlavní obsah
Konfigurace webhooků v Integracích

Nastavení > Integrace & API

Tabulka webhooků s událostí, URL, stavem, datem vytvoření a otevřenou nabídkou akcí řádku

Nastavení > Integrace & API > Webhooky

Webhooky upozorní váš systém, když se v TWICE Commerce změní objednávka. Když událost nastane, TWICE odešle HTTP POST na URL, kterou zaregistrujete, takže můžete reagovat bez dotazování API.

Typy událostí

TWICE odesílá tři události objednávek: Pole data v payloadu obsahuje dotčenou objednávku (Order). Postupem času mohou přibýt další zdroje a události.

Co spouští order.updated

order.updated nastane, když se změní samotná objednávka, a také když se změní kterákoli její podřízená data:
  • Řádky položek
  • Skladové položky
  • Zákazníci
  • Komentáře
  • Štítky
  • Dokumenty
  • Slevy
  • Atributy
  • Pole pokladny
Záznamy plateb v této sadě nejsou. Zápis platby sám order.updated nespustí. Jedna operace, která zasáhne více podřízených řádků (například hromadná úprava, která v jedné transakci změní objednávku a několik řádků položek), vyvolá jedno doručení, ne více. TWICE sloučí nárazové změny podle objednávky, takže váš endpoint dostane jedinou souhrnnou událost.
Potlačení čekajících objednávek (rozpracované koncepty z pokladny) platí jen pro vytvoření: vložení čekající objednávky nic neodešle a order.created nastane, když objednávka opustí stav čekající. Aktualizace čekající objednávky stále odesílají order.updated a její smazání odešle order.deleted.

Jak to funguje

Každé doručení je HTTP POST, jehož tělem je JSON obálka popisující událost. Dotčený zdroj putuje v poli data:
string
Jedinečný identifikátor události. Posílá se i v hlavičce X-Twice-Event-Id. Deduplikujte podle této hodnoty.
string
Událost, která nastala, například order.created. Jeden webhook přijímá jeden typ události.
string
Časové razítko ISO 8601 okamžiku, kdy událost nastala.
string
Zdroj, kterého se událost týká, například order.
string
Identifikátor dotčeného zdroje.
string
Verze API, ve které je payload vykreslen.
object | null
Zdroj ve stejném tvaru, v jakém ho vrací REST API. U order.deleted je null.
Schéma objednávky v poli data najdete v referenci API.

Připnutí verze API

Každý webhook je připnutý na verzi API, která byla nejnovější v době jeho vytvoření, a tato verze se uvádí v apiVersion. Nová verze API nikdy nezmění tvar payloadu, který už přijímáte. Přesun webhooku na novější verzi je vždy výslovná aktualizace.

Správa webhooků

Webhooky spravujte v Nastavení → Integrace & API → Webhooky. Vytvořte webhook výběrem typu události a zadáním URL endpointu, který POST přijme. Cílové URL musí být HTTPS. Tabulka uvádí u každého webhooku: Zbytek pokrývají akce řádku: Zobrazit doručení, Povolit / Zakázat, Zobrazit signing secret a Smazat. Jedna událost může být doručena několika webhookům, například jeden webhook order.created do vašeho CRM a druhý do účetního systému.

Doručení a opakování

TWICE doručuje webhooky asynchronně přes frontu Cloud Tasks. Doručení uspěje při jakékoli odpovědi 2xx. Každý jiný stav, nebo vypršení časového limitu, se počítá jako neúspěšný pokus. Neúspěšné doručení se opakuje nejvýše 3krát (celkem 4 pokusy), zhruba 10 s, 20 s a 40 s po předchozím pokusu, a opakování končí 10 minut po prvním pokusu. Když vyčerpají všechny pokusy 3 události za sebou, webhook se automaticky zakáže s důvodem TOO_MANY_FAILED_DELIVERY_ATTEMPTS. Znovu ho povolte ručně, jakmile bude váš endpoint dostupný. Opětovné povolení, nebo přesměrování webhooku na jinou URL, zahájí nové okno selhání. Odpovídejte 2xx rychle. Pokud je zpracování pomalé, doručení nejdřív potvrďte a práci zařaďte do fronty.

Protokol doručení

Každé odeslané doručení se zaznamenává. Otevřete Zobrazit doručení u webhooku a uvidíte je na adrese /settings/connect/integrations/webhooks/{webhookId}, s filtrováním a řazením podle výsledku, události, ID události, času spuštění, počtu pokusů a poslední odpovědi.
Protokol doručení s otevřeným panelem detailu doručení zobrazujícím časovou osu pokusů a payload

Detail doručení: časová osa pokusů a podepsaná obálka payloadu

Doručení má jeden ze čtyř stavů: Otevřením řádku zobrazíte detail doručení: ID události, čas spuštění, počet pokusů a poslední odpověď, časovou osu pokusů s výsledkem každého pokusu a přesný odeslaný payload. Odtud můžete Zkopírovat payload, nebo pomocí Znovu doručit odeslat stejný zaznamenaný payload na cílovou URL znovu.
Doručení zaznamenaná dříve, než protokol doručení začal ukládat payloady, payload nezobrazují a nelze je znovu doručit.
Testovací doručení neexistuje. Endpoint vyzkoušíte před nasměrováním produkčního provozu tak, že vytvoříte webhook na dočasnou URL (dialog vytvoření navrhuje webhook.site) a spustíte událost.

Deduplikace

Stejná událost může dorazit více než jednou, takže váš endpoint musí být idempotentní. Deduplikujte podle eventId, který se posílá v těle i v hlavičce X-Twice-Event-Id. Pořadí také není zaručeno. Když na pořadí záleží, porovnejte eventTime, nebo si aktuální stav zdroje znovu načtěte přes API.

Ověření podpisů

Každý webhook má signing secret s prefixem whsec_. TWICE jím podepisuje každé doručení a podpis posílá v hlavičce X-Twice-Signature ve formátu sha256=<hex>, což je HMAC-SHA256 přesného syrového těla požadavku. Ověřujte proti bajtům syrového těla a JSON zpracujte až po úspěšné kontrole podpisu:

Správa secretu

Otevřete Zobrazit signing secret u webhooku, abyste secret zobrazili, zkopírovali nebo obnovili.
Obnovení nahradí secret okamžitě. Doručení se od té chvíle podepisují novým secretem, takže svůj endpoint aktualizujte ve stejnou dobu.
Webhooky vytvořené před zavedením podepisování secret nemají a jejich doručení zůstávají nepodepsaná, dokud ho nevygenerujete. Dialog pro ně nabízí Vygenerovat secret.

Reference pro vývojáře

Webhooky se spravují přes endpointy hooks.

API: Webhook Subscriptions

Otevřít endpoint v referenci API.

Související články

Integrace

Webhooky vedle klíčů API.

Klíče API

Ověřování vůči API.

Protokoly aktivit

Auditní stopa, se kterou můžete data sesouhlasit.

Životní cyklus objednávky

Kdy se události objednávek spouštějí.