> ## Documentation Index > Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Webhooky > Jak TWICE Commerce doručuje podepsaná oznámení o událostech objednávek na váš endpoint metodou HTTP POST. ![Konfigurace webhooků v Integracích](https://mintcdn.com/twicecommerce/lZhc_tO8u1u_bL0Q/images/settings-integrations.webp?fit=max\&auto=format\&n=lZhc_tO8u1u_bL0Q\&q=85\&s=40fdc769db7318c16cae719abf0e7dd0) Nastavení > Integrace & API ![Tabulka webhooků s událostí, URL, stavem, datem vytvoření a otevřenou nabídkou akcí řádku](https://mintcdn.com/twicecommerce/yRIgvb0PY9wrSJi9/images/settings-webhooks-table.webp?fit=max\&auto=format\&n=yRIgvb0PY9wrSJi9\&q=85\&s=99114fe3ea23f1406dea39e426f5ea56) 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: | Událost | Kdy nastane | | :- | :- | | `order.created` | Vytvoří se nová objednávka | | `order.updated` | Změní se objednávka nebo kterákoli její podřízená data | | `order.deleted` | Objednávka se smaže | 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. > [!NOTE] > > 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`: ```json theme={null} { "eventId": "5f2eb3a6-6cbd-4a2e-9350-6e0d1e2f9a11", "eventType": "order.created", "eventTime": "2026-08-11T12:34:56.789Z", "resource": "order", "resourceId": "0d9e0a7c-3fd1-4c8f-9c0d-2b7c6f7f2a55", "apiVersion": "2025-06", "data": { "id": "0d9e0a7c-3fd1-4c8f-9c0d-2b7c6f7f2a55", "…": "the full Order object" } } ``` **eventId** `string` Jedinečný identifikátor události. Posílá se i v hlavičce `X-Twice-Event-Id`. Deduplikujte podle této hodnoty. **eventType** `string` Událost, která nastala, například `order.created`. Jeden webhook přijímá jeden typ události. **eventTime** `string` Časové razítko ISO 8601 okamžiku, kdy událost nastala. **resource** `string` Zdroj, kterého se událost týká, například `order`. **resourceId** `string` Identifikátor dotčeného zdroje. **apiVersion** `string` Verze API, ve které je payload vykreslen. **data** `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](https://www.twicecommerce.com/docs/api-reference/orders). ### 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: | Sloupec | Popis | | :- | :- | | **Událost** | Jediný typ události, který tento webhook přijímá | | **URL** | HTTPS endpoint, na který se payload odesílá metodou POST | | **Stav** | Aktivní, nebo Zakázáno. Důvod zobrazíte najetím na štítek | | **Vytvořeno** | Kdy byl webhook vytvořen | 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](https://mintcdn.com/twicecommerce/xUE4mkDkj1E022kJ/images/webhook-delivery-log.webp?fit=max\&auto=format\&n=xUE4mkDkj1E022kJ\&q=85\&s=262c4ac0b7e8b7b42879bd1208e53fad) Detail doručení: časová osa pokusů a podepsaná obálka payloadu Doručení má jeden ze čtyř stavů: | Stav | Význam | | :- | :- | | **Čeká na vyřízení** | Zařazeno do fronty, zatím není zaznamenán výsledek pokusu | | **Opakuje se pokus** | Pokus selhal a je naplánován další | | **Doručeno** | Pokus vrátil `2xx` | | **Selhalo** | Všechny pokusy selhaly | 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. > [!NOTE] > > 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](https://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=`, 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: ```javascript Node.js (Express) theme={null} import express from 'express'; import { createHmac, timingSafeEqual } from 'node:crypto'; const app = express(); const secret = process.env.TWICE_WEBHOOK_SECRET; // Raw body: the signature covers the exact bytes TWICE sent app.post('/webhooks/order-created', express.raw({ type: 'application/json' }), (req, res) => { const expected = 'sha256=' + createHmac('sha256', secret).update(req.body).digest('hex'); const signature = req.get('X-Twice-Signature'); const isValid = typeof signature === 'string' && signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); if (!isValid) return res.status(401).send('Invalid signature'); const event = JSON.parse(req.body.toString('utf8')); handleOrderCreated(event.eventId, event.data); res.status(200).send('OK'); }); app.listen(3000); ``` ```python Python (Flask) theme={null} import hmac, hashlib, json, os from flask import Flask, request app = Flask(__name__) secret = os.environ['TWICE_WEBHOOK_SECRET'] @app.post('/webhooks/order-created') def order_created(): raw_body = request.get_data() expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() signature = request.headers.get('X-Twice-Signature', '') if not hmac.compare_digest(signature, expected): return ('Invalid signature', 401) event = json.loads(raw_body) handle_order_created(event['eventId'], event['data']) return ('OK', 200) ``` ### Správa secretu Otevřete **Zobrazit signing secret** u webhooku, abyste secret zobrazili, zkopírovali nebo obnovili. > [!WARNING] > > 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](https://www.twicecommerce.com/docs/api-reference/webhook-subscriptions)** > > Otevřít endpoint v referenci API. ## Související články > **[Integrace](https://www.twicecommerce.com/docs/cs/concepts/integrations/overview.md)** > > Webhooky vedle klíčů API. > **[Klíče API](https://www.twicecommerce.com/docs/cs/concepts/integrations/api-keys.md)** > > Ověřování vůči API. > **[Protokoly aktivit](https://www.twicecommerce.com/docs/cs/concepts/admin/activity-logs.md)** > > Auditní stopa, se kterou můžete data sesouhlasit. > **[Životní cyklus objednávky](https://www.twicecommerce.com/docs/cs/concepts/orders/order-lifecycle.md)** > > Kdy se události objednávek spouštějí. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.