Webhooky

• conversation.startedZačíná nová konverzace, ve widgetu nebo na připojeném kanálu.
• message.createdDo konverzace se uloží zpráva, od návštěvníka, asistenta nebo operátora.
• handover.requestedKonverzace poprvé žádá o člověka, eskalováno asistentem.
• handover.claimedOperátor převzal konverzaci a připojil se do ní. Ve dvojici s handover.requested změříte, jak dlouho návštěvníci čekají na člověka.
• custom_action.executedVe webovém widgetu se dokončí potvrzená akce měnící data. Akce jen pro čtení místo toho spustí custom_action.read a operátorovo vlastní testovací volání z dashboardu nespustí ani jednu z nich. Akce měnící data dnes běží pouze ve webovém widgetu, takže tato událost nikdy nepřijde z připojeného kanálu.
• custom_action.readDokončí se akce jen pro čtení, ve widgetu nebo v připojeném kanálu. Tato událost i custom_action.executed nesou argumenty, se kterými asistent akci zavolal, takže vidíte, koho nebo co vyhledával. Ani jedna nenese odpověď vašeho endpointu.
• endpoint.testOdesílá se pouze tlačítkem Send test v dashboardu, přes skutečnou doručovací frontu, bez ohledu na to, jaké události má endpoint nastavené.

1. 01
   Vytvořte endpoint

   V dashboardu otevřete v Nastavení Webhooky a přidejte endpoint. URL musí být HTTPS; pokud jich plánujete víc, přidejte i popisek.
2. 02
   Přihlaste se k odběru událostí

   Vyberte, které typy událostí z katalogu výše mají na tento endpoint chodit. Můžete si vybrat libovolnou podmnožinu a výběr kdykoli později změnit.
3. 03
   Ověřte podpis

   Každé doručení je podepsané. Ověřte ho, než tělu požadavku uvěříte, podle schématu níže v části Ověření doručení.
4. 04
   Odešlete test

   Tlačítkem Send test na endpointu spustíte skutečné doručení endpoint.test celou frontou, zařazené a podepsané přesně jako ostrý provoz, takže si ověříte svého klienta ještě předtím, než se na něj spolehnete.

1. 01
   Vytvořte Zap se spouštěčem Catch Hook

   V Zapieru založte nový Zap a jako aplikaci spouštěče zvolte Webhooks by Zapier, událost Catch Hook. Zapier vám vygeneruje vlastní webhookovou URL. Zkopírujte si ji.
2. 02
   Přidejte URL jako endpoint v Breezaru

   V dashboardu otevřete v Nastavení Webhooky, přidejte endpoint a vložte do něj URL ze Zapieru. Přihlaste ho k odběru událostí, na které má Zap reagovat, ideálně jen k těm, které opravdu potřebuje, a uložte.
3. 03
   Vyvolejte skutečnou událost

   Dokud Zapier nezachytí skutečný požadavek, žádná pole vám neukáže. Nechte otevřený testovací krok Zapu a událost opravdu vyvolejte: u conversation.started začněte konverzaci na svém webu, u handover.requested požádejte asistenta o člověka. Pak v Zapieru spusťte Test trigger.
4. 04
   Namapujte pole do akce

   Přidejte akční krok (Tabulky Google, Slack, vaše CRM) a namapujte do něj načtená pole. Zapier vnořenou obálku zploští, takže id konverzace se obvykle objeví pod názvem jako data__conversation__id.
5. 05
   Zapněte Zap

   Zap publikujte a od té chvíle ho spustí každá odpovídající událost. První den sledujte u endpointu seznam Doručení v Breezaru: u každé události ukazuje návratový kód, který Zapier vrátil, což je nejrychlejší způsob, jak odhalit Zap, který požadavky odmítá.

Pole, která stojí za to mapovat, a kde je najdete, jakmile Zapier payload zploští:

Make, n8n, Pipedream a podobné nástroje fungují stejně: dají vám URL, která požadavky zachytává, a všechno výše pro ně platí beze změny, včetně poznámky o podpisu.

S každým doručením jdou tři hlavičky: webhook-id (id události, stejné při každém opakovaném doručení), webhook-timestamp (unixový čas v sekundách v okamžiku odeslání) a webhook-signature. Každý požadavek má také content-type: application/json a user-agent: Breezaro-Webhooks/1.

webhook-signature je verze a podpis spojené čárkou: doslovné v1, následované base64 otiskem. Vezměte část tajného klíče endpointu za whsec_ a dekódujte ji z base64; to je váš klíč HMAC-SHA256. Podepište id události, tečku, timestamp, další tečku a tělo požadavku, spojené do jednoho řetězce přesně v tomto pořadí (viz pseudokód níže), a výsledek zakódujte do base64. Měl by se shodovat s částí hlavičky za v1,.

signedContent = webhookId + '.' + webhookTimestamp + '.' + rawRequestBody
key           = base64Decode(secret.slice('whsec_'.length))
expected      = 'v1,' + base64Encode(hmacSha256(key, signedContent))

if (!constantTimeEqual(expected, webhookSignatureHeader)) reject('bad signature')
if (Math.abs(nowInSeconds() - Number(webhookTimestamp)) > 300) reject('stale timestamp')

id je pole pro deduplikaci. type je jeden z názvů událostí výše. createdAt je okamžik, kdy událost nastala, ne kdy se odeslal tento konkrétní pokus. apiVersion je dnes pevný řetězec a mění se jen při zásadní změně tvaru payloadu. data nese vlastní pole události, vždy vedle objektu conversation s id a source konverzace.

{
  "id": "evt_2b6f7e3a-9c9b-4a91-8ce1-7b6dcd6db8a2",
  "type": "conversation.started",
  "createdAt": "2026-07-29T14:03:11.482Z",
  "apiVersion": "2026-07-29",
  "data": {
    "conversation": {
      "id": "cm3qf8x3k0007jr08g6z1a2b3",
      "source": "widget"
    },
    "startedAt": "2026-07-29T14:03:11.482Z",
    "visitor": {
      "language": "en",
      "countryCode": "US",
      "deviceType": "desktop"
    }
  }
}

message.created označuje roli každé zprávy jako visitor, bot nebo operator; interní systémové značky, například vstup nebo odchod operátora z konverzace, se jako zprávy nikdy neodesílají. U odpovědi bota na kanálu znamená message.created, že se zpráva uložila, ne že ji poskytovatel kanálu už doručil návštěvníkovi.

Každá událost dostane až 8 pokusů o doručení rozložených zhruba do 6 hodin, s rozestupy asi 30 sekund, 2 minuty, 10 minut, 30 minut, 1 hodina, 2 hodiny a 2 hodiny (každý náhodně upravený o zhruba ±20 %, aby opakované pokusy nepřicházely všechny najednou).

• Až 3 endpointy na asistenta.
• Vyžaduje tarif Standard nebo vyšší (případně aktivní zkušební dobu). Pokud váš tarif přestane webhooky zahrnovat, endpointy se automaticky vypnou a dostanete upozornění v dashboardu; po upgradu je znovu zapnete v dashboardu.
• Doručení jsou zdarma: odeslání ani opakování webhooku nikdy nestojí kredity.
• URL endpointu musí být HTTPS; požadavky na privátní či interní síťové adresy jsou blokované, stejně jako u vlastních akcí.
• Váš endpoint má na odpověď se stavem 2xx 10 sekund. Obsah odpovědi ignorujeme, ale udržte ji do 2 MB; větší odpověď se považuje za neúspěšné doručení. Přesměrování se počítá jako selhání, ne jako úspěch.
• Dashboard uchovává nejnovější doručení každého endpointu 30 dní a poté je odstraní.
• Jeden endpoint může mít nejvýše 1000 čekajících doručení. Dokud je fronta takto plná, nové události se pro něj zahazují místo řazení do fronty, takže selhávající endpoint opravte nebo vypněte, ať se doručení nehromadí.