
Nastavení > Integrace & API

Nastavení > Integrace & API > Webhooky
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
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 HTTPPOST, 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.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í vapiVersion. 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ědi2xx. 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.

Detail doručení: časová osa pokusů a podepsaná obálka payloadu
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.
Deduplikace
Stejná událost může dorazit více než jednou, takže váš endpoint musí být idempotentní. Deduplikujte podleeventId, 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 prefixemwhsec_. 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. 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 endpointyhooks.
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í.