Webhooks

Přehled webhooků

Webhooky umožňují službě ChatLab upozornit vaše systémy v okamžiku, kdy se v chatbotech něco stane. Místo pravidelného dotazování Management API nebo ručního exportu dat zaregistrujete HTTPS koncový bod a ChatLab na něj v reálném čase odešle podepsaný HTTP POST - když návštěvník zanechá lead, odešle kontaktní formulář, ohodnotí konverzaci, požádá o lidského operátora nebo když proběhne akce AI.

Typická využití:

• odesílání nových leadů přímo do vašeho CRM ihned po jejich zachycení
• upozornění týmu ve Slacku, když návštěvník požádá o live chat (živý chat)
• předávání hodnocení a shrnutí konverzací do vašich vlastních analytických nástrojů
• sledování spouštění akcí AI a upozorňování na chyby

Dostupnost: webhooky jsou dostupné od plánu STANDARD výše (funkce: Webhooks).

Kde je nastavit: v administrátorské aplikaci otevřete Account settings -> Webhooks (Nastavení účtu -> Webhooky; hned vedle sekce Management API). Webhooky fungují na úrovni účtu - jeden koncový bod může přijímat události ze všech vašich botů nebo pouze z vybrané filtrované skupiny.

Nastavení koncového bodu

1. Otevřete Account settings -> Webhooks a klikněte na Create endpoint (Vytvořit koncový bod).
2. Vyplňte formulář koncového bodu:
   • Name (Název) - označení pro vaši vlastní potřebu, např. „Synchronizace CRM" nebo „Upozornění do Slacku".
   • URL - adresa HTTPS, na kterou bude ChatLab odesílat události metodou POST.
   • Events (Události) - vyberte typy událostí, které má tento koncový bod přijímat (viz katalog níže). Zvolte pouze ty, které skutečně potřebujete; události s vysokou frekvencí jako ai_action.executed mohou generovat značný provoz.
   • Bot filter (volitelné) - omezí koncový bod na konkrétní boty. Ponechte prázdné, pokud chcete přijímat události ze všech botů na svém účtu.
   • Custom form filter (volitelné) - směruje odeslání jednoho vlastního formuláře na tento koncový bod. Zužuje pouze událost custom_form.submitted; všechny ostatní odebírané události (leady, žádosti o kontakt, konverzace, live chat, akce AI) jsou doručovány bez ohledu na toto nastavení.
3. Potvrďte odeslání. Tajný klíč (secret) koncového bodu se zobrazí přesně jednou v potvrzovacím okně - ihned si jej zkopírujte a bezpečně uložte. Budete jej potřebovat k ověřování podpisů (viz část Zabezpečení níže). V čitelné podobě jej již později nelze znovu získat.

Každý koncový bod dále obsahuje:

• Přepínač aktivace/deaktivace (Enable/disable toggle) - pozastaví doručování bez nutnosti smazat koncový bod. Vypnuté koncové body události tiše zahazují (nezařazují se do fronty na později).
• Send sample event (Odeslat ukázkovou událost) - odešle podepsaný testovací požadavek na vaši URL adresu, abyste si mohli ověřit funkčnost celého řetězce přijímače. Můžete si vybrat typ události a před odesláním upravit ukázkové hodnoty, aby váš handler zpracoval realistická data. Test dorazí jako běžné doručení s parametrem eventType odpovídajícím vaší volbě (nebo jako webhook.test pro prosté ověření konektivity).
• Roll secret (Pravidelná obměna tajného klíče) - vygeneruje nový secret a zneplatní ten starý. Tuto možnost využijte, pokud došlo k úniku tajného klíče. Nový secret se opět zobrazí pouze jednou. Před jeho obměnou nezapomeňte aktualizovat svůj přijímač, jinak u doručovaných požadavků selže ověření podpisu na vaší straně.
• Delivery log (Protokol doručení) - seznam nedávných doručení pro daný koncový bod s časovým razítkem, typem události, HTTP stavem vráceným vaším serverem a dobou odezvy. Zde jsou viditelná i neúspěšná doručení a pozastavení vyvolaná pojistkou proti přetížení (circuit breaker). Protokol se uchovává po dobu 14 dnů.

Obálka události (envelope)

Každé doručení probíhá formou HTTP POST s hlavičkou Content-Type: application/json. Tělo má vždy stejnou obálku; objekt data se liší podle typu události:

{
  "eventId": "9f1c1c8e-6a2b-4b9e-9d2f-3f8a1e2b4c5d",
  "eventType": "lead.created",
  "timestamp": "2026-08-13T14:22:31Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": { }
}

• eventId - unikátní pro každou událost. Využijte jej k deduplikaci, pokud vaše zpracování musí být idempotentní.
• eventType - jeden z níže popsaných typů; odesílá se také v hlavičce X-ChatLab-Event.
• timestamp - čas vzniku události ve formátu ISO 8601 UTC.
• botId / botName - bot, ke kterému událost patří.
• conversationId / sessionId - kontext konverzace, je-li k dispozici.

Katalog událostí

lead.created

Spustí se ve chvíli, kdy návštěvník odešle své kontaktní údaje - prostřednictvím formuláře pro sběr leadů, úvodního formuláře před live chatem nebo vlastního formuláře sloužícího ke sběru leadů.

{
  "eventId": "9f1c1c8e-6a2b-4b9e-9d2f-3f8a1e2b4c5d",
  "eventType": "lead.created",
  "timestamp": "2026-08-13T14:22:31Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "email": "jane.doe@example.com",
    "name": "Jane Doe",
    "phone": "+1 555 0123",
    "source": "LEAD_COLLECTION_FORM",
    "formCodeName": "lead_form",
    "formName": "Lead form",
    "fields": [
      {"name": "email", "value": "jane.doe@example.com", "type": "email"},
      {"name": "company", "value": "Acme Inc.", "type": "text"},
      {"name": "topics", "value": ["Billing", "Delivery"], "type": "multichoice"},
      {"name": "attachment", "value": "https://api.chatlab.com/aichat/customform/download?key=...&token=...", "type": "file"}
    ],
    "pageUrl": "https://acme.com/pricing"
  }
}

• source - způsob získání kontaktních údajů: LEAD_COLLECTION_FORM (formulář pro sběr leadů), LIVE_CHAT_FORM (úvodní formulář live chatu), CONVERSATION (AI údaje zachytila během konverzace), ADMIN_DATA_UPDATE nebo UPDATE_CLIENT_CONTEXT (upraveno na straně ChatLabu). Odeslání formuláře pro lidskou podporu tuto událost nikdy nespouští - místo toho vyvolá contact_form.submitted.
• email, name, phone - kontaktní údaje namapované do záznamu leadu.
• Pokud se pro sběr leadů použije vlastní formulář, pole fields obsahuje každé pole definované v tomto formuláři v pořadí z formuláře a formCodeName / formName identifikují formulář. U klasického formuláře pro sběr leadů mají obě hodnoty hodnotu null a pole fields je prázdné pole.
• Každá položka v fields má formát {name, value, type}. name představuje technický název pole, který se nemění ani při úpravách popisku - použijte jej pro mapování do vašeho CRM.
• U polí typu multichoice je value polem (array) vybraných možností. Zaškrtávací pole představují samostatné položky s hodnotami "true" / "false".
• U polí typu file je value odkazem ke stažení nahraného souboru; webhook samotný obsah souboru nikdy nepřenáší.
• pageUrl - stránka, na které se návštěvník při odeslání nacházel.

contact_form.submitted

Spustí se ve chvíli, kdy návštěvník odešle kontaktní formulář pro lidskou podporu nebo vlastní formulář určený pro kontakt s člověkem.

{
  "eventId": "3a7b9c2d-1e4f-4a6b-8c0d-5e2f7a9b1c3d",
  "eventType": "contact_form.submitted",
  "timestamp": "2026-08-13T14:25:02Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "email": "jane.doe@example.com",
    "message": "I need help with my last invoice.",
    "source": "CUSTOM_FORM",
    "formCodeName": "contact_form",
    "formName": "Contact form",
    "fields": [
      {"name": "email", "value": "jane.doe@example.com", "type": "email"},
      {"name": "order_number", "value": "A-10293", "type": "text"},
      {"name": "message", "value": "I need help with my last invoice.", "type": "textarea"}
    ]
  }
}

• email - adresa zadaná návštěvníkem, na kterou by měl váš tým podpory odpovědět.
• source - hodnota CUSTOM_FORM, pokud je kontaktní formulář tvořen vlastním formulářem, nebo CONTACT_FORM u výchozího vestavěného formuláře.
• formCodeName / formName - identifikují vlastní formulář za požadavkem; u výchozího formuláře mají obě hodnoty hodnotu null.
• Při použití vlastního formuláře jsou v fields obsažena všechna pole definovaná v tomto formuláři (ve stejném formátu {name, value, type} jako u lead.created). U vestavěného kontaktního formuláře se vyplňují pouze pole email a message, fields je prázdné pole a identifikátory formuláře mají hodnotu null.
• message - namapované pole zprávy nebo všechny vyplněné hodnoty spojené dohromady, pokud formulář samostatné pole pro zprávu nedefinuje.

custom_form.submitted

Spustí se při každém odeslání vlastního formuláře bez ohledu na jeho účel. Upozorňujeme, že formuláře, jejichž účelem je sběr leadů nebo kontaktování člověka, navíc spouštějí svou vyhrazenou událost lead.created / contact_form.submitted - přihlaste se k odběru jedné nebo druhé podle toho, zda chcete obecný nebo specializovaný přehled, a pokud odebíráte obě, provádějte deduplikaci podle conversationId + timestamp.

{
  "eventId": "6c1d8e3f-2a5b-4c7d-9e0f-1a4b6c8d0e2f",
  "eventType": "custom_form.submitted",
  "timestamp": "2026-08-13T14:27:45Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "formCodeName": "warranty_claim",
    "formName": "Warranty claim",
    "fields": [
      {"name": "order_number", "value": "A-10293", "type": "text"},
      {"name": "issue", "value": "Damaged on arrival", "type": "textarea"},
      {"name": "photo", "value": "https://api.chatlab.com/aichat/customform/download?key=...&token=...", "type": "file"}
    ],
    "purpose": "STANDALONE"
  }
}

• formCodeName - stálý systémový název formuláře, který se nemění při přejmenování formuláře; slouží ke směrování odeslaných dat ve vašem vlastním systému. formName je zobrazovaný název viditelný pro návštěvníky.
• fields používá stejné položky {name, value, type} jako lead.created: vícenásobné volby jsou pole hodnot, soubory jsou odkazy ke stažení.
• purpose - STANDALONE, LEAD_COLLECTION nebo HUMAN_CONTACT podle toho, jak je formulář v chatbotu zapojen.

conversation.started

Spustí se ve chvíli, kdy návštěvník odešle první zprávu nové konverzace.

{
  "eventId": "8e2f0a4b-3c6d-4e8f-a1b2-2c5d7e9f1a3b",
  "eventType": "conversation.started",
  "timestamp": "2026-08-13T14:20:11Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "firstMessage": "Do you ship to Canada?",
    "chatSource": "WIDGET",
    "byAdmin": false,
    "countryCode": "PL",
    "ipAddress": "83.12.44.7"
  }
}

• firstMessage - přesný text úvodní zprávy návštěvníka. Hodnota null, pokud byla konverzace zahájena bez textu zprávy.
• chatSource - kanál, přes který konverzace přišla: WIDGET, WHATSAPP, MESSENGER, VOICE, VOICE_PHONE, API, BOOKING, AIRBNB nebo IDOBOOKING.
• byAdmin - hodnota true, pokud konverzace pochází z náhledu chatbota v administrátorském panelu ChatLabu a ne od skutečného návštěvníka. Využijte tento údaj k odfiltrování vlastních testovacích chatů z CRM.
• countryCode - kód země podle ISO určený z IP adresy návštěvníka; null, pokud se jej nepodařilo zjistit.
• ipAddress - IP adresa návštěvníka zjištěná ChatLabem; null, pokud není dostupná. Podle nařízení GDPR jde o osobní údaj, ukládejte jej proto pouze v případě, že k tomu máte právní základ.

conversation.rated

Spustí se ve chvíli, kdy návštěvník ohodnotí odpověď bota palcem nahoru nebo dolů (viz Hodnocení konverzace).

{
  "eventId": "1b4c6d8e-5f0a-4b2c-8d3e-4f7a9b1c3d5e",
  "eventType": "conversation.rated",
  "timestamp": "2026-08-13T14:31:09Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "rating": "POSITIVE"
  }
}

• rating - POSITIVE nebo NEGATIVE. Zrušení hodnocení tuto událost nespouští, neutrální hodnotu tedy nikdy neobdržíte.

conversation.summarized

Spustí se ve chvíli, kdy ChatLab vygeneruje shrnutí ukončené konverzace.

{
  "eventId": "4d7e9f1a-6b2c-4d4e-9f0a-5b8c0d2e4f6a",
  "eventType": "conversation.summarized",
  "timestamp": "2026-08-13T14:45:00Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "summary": "Visitor asked about shipping to Canada and delivery times. The bot confirmed availability and quoted 5-7 business days. Visitor left satisfied.",
    "language": "en"
  }
}

• summary - vygenerovaný text shrnutí. Shrnutí vznikají několik minut poté, co konverzace přejde do neaktivity, proto tato událost přichází později než ostatní události konverzace.
• language - kód jazyka podle ISO, ve kterém bylo shrnutí vytvořeno; odpovídá jazyku konverzace.

client.summarized

Spustí se ve chvíli, kdy ChatLab aktualizuje profil klienta vytvořený pomocí AI. Profil se znovu sestavuje z předchozího profilu a shrnutí právě ukončené konverzace, tato událost tedy navazuje na conversation.summarized ze stejné konverzace. Klienti jsou identifikováni e-mailem, proto se adresa opakuje přímo na nejvyšší úrovni objektu data.

{
  "eventId": "b5d8f1a3-7c2e-4d9b-a6f0-1e3c5a7b9d2f",
  "eventType": "client.summarized",
  "timestamp": "2026-08-18T09:12:04Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "clientEmail": "jane.doe@example.com",
    "client": {
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "phone": "+1 555 0123",
      "countryCode": "PL",
      "ipAddress": "83.12.44.7"
    },
    "clientSummary": "Returning customer interested in international shipping. Asked about delivery times to Canada twice and about return costs once."
  }
}

• clientEmail - identifikátor sloužící ke spárování klienta s vaším vlastním CRM. U anonymních návštěvníků, kteří adresu nikdy nezadali, má hodnotu null (i pro ně se však událost odesílá - tato doručení přeskočte, pokud je vaše integrace navázána na e-mail).
• client - záznam kontaktu, který ChatLab o dané osobě eviduje: email, name, phone, countryCode a ipAddress. Každý z klíčů je přítomen vždy; neznámé hodnoty mají hodnotu null.
• clientSummary - kompletní text profilu v prostém textu, nejedná se o rozdílový zápis (diff). Nahrazuje jakékoli předchozí shrnutí, ukládejte jej proto přepsáním původních dat, nikoli přidáváním na konec.
• Profil se znovu vytváří pouze u botů s aktivní funkcí paměť chatu a pouze u konverzací, které byly neaktivní dostatečně dlouho na to, aby došlo k vytvoření shrnutí - tuto událost očekávejte několik minut po skončení konverzace, nikoli okamžitě.

live_chat.requested

Spustí se ve chvíli, kdy AI předá konverzaci do live chatu (živého chatu) - buď proto, že si návštěvník vyžádal člověka, nebo proto, že bot sám vyhodnotil přítomnost operátora jako nezbytnou.

{
  "eventId": "7a0b2c4d-8e3f-4a5b-b0c1-6d9e1f3a5b7c",
  "eventType": "live_chat.requested",
  "timestamp": "2026-08-13T14:33:20Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "requestedBy": "AI"
  }
}

• requestedBy - v současnosti vždy AI, protože předání je vždy vyvoláno akcí live chatu ze strany bota, a to i v případě, kdy o něj návštěvník požádá běžnými slovy. Pracujte s tímto polem jako s otevřeným výčtem: ošetřete neznámé hodnoty a nespoléhejte se striktně pouze na hodnotu AI.
• Událost informuje o tom, že předání bylo vyžádáno, nikoli že jej operátor již převzal. Na samotné převzetí vyčkejte na událost live_chat.started.

live_chat.started

Spustí se ve chvíli, kdy se operátor připojí a relace live chatu skutečně začne.

{
  "eventId": "0c3d5e7f-9a4b-4c6d-a1b2-7e0f2a4b6c8d",
  "eventType": "live_chat.started",
  "timestamp": "2026-08-13T14:33:55Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {}
}

• Objekt data je záměrně prázdný. Všechny potřebné informace obsahuje obálka: botId určuje chatbota a conversationId / sessionId propojují událost s konverzací, pro kterou jste již obdrželi live_chat.requested.

live_chat.ended

Spustí se ve chvíli, kdy relace live chatu skončí.

{
  "eventId": "2e5f7a9b-0c5d-4e7f-b2c3-8f1a3b5c7d9e",
  "eventType": "live_chat.ended",
  "timestamp": "2026-08-13T14:52:41Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "durationSeconds": 1126
  }
}

• durationSeconds - celková doba přítomnosti operátora v konverzaci počítaná od okamžiku zahájení relace. Ve vzácných případech, kdy relace skončí, aniž by byla reálně zahájena, se toto pole vynechává.

ai_action.executed

Spustí se při každém provedení akce AI botem - ať už jde o volání spravované integrace nebo vlastní funkci API. Jedná se o událost s velmi vysokou frekvencí: aktivní e-commerce bot může provést stovky akcí denně a jediný dotaz návštěvníka jich může vyvolat několik. Přihlaste se k jejímu odběru na vyhrazeném koncovém bodu, případně se ujistěte, že váš přijímač zvládne takový objem zpracovat.

{
  "eventId": "5f8a0b2c-1d6e-4f8a-c3d4-9a2b4c6d8e0f",
  "eventType": "ai_action.executed",
  "timestamp": "2026-08-13T14:21:03Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "actionName": "search_products",
    "status": "SUCCESS",
    "durationMs": 842,
    "errorMessage": null
  }
}

• actionName - název provedené akce z pohledu AI, například search_products u spravované integrace nebo název, který jste přiřadili vlastní akci API.
• status - SUCCESS nebo ERROR.
• durationMs - doba provádění akce v milisekundách. Pomáhá odhalit pomalou integraci dříve, než na ni začnou upozorňovat návštěvníci.
• errorMessage - důvod selhání vyplněný pouze v případě, kdy má status hodnotu ERROR; v opačném případě má hodnotu null.

webhook.test

Odesílá se stisknutím tlačítka Send sample event při provádění prosté kontroly konektivity. Požadavek je podepsán zcela shodně jako skutečná událost.

{
  "eventId": "9b2c4d6e-3f8a-4b0c-d5e6-0b3c5d7e9f1a",
  "eventType": "webhook.test",
  "timestamp": "2026-08-13T14:10:00Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "message": "Test delivery from ChatLab"
  }
}

• message - neměnný text, který je vždy stejný. Pole obálky obsahují ukázkové hodnoty, proto doručení typu webhook.test nikdy nepovažujte za skutečná data.
• Jedná se o jediný typ události, k jehož odběru se u koncového bodu nelze přímo přihlásit: odesílá se na vyžádání z administrátorského panelu a vždy dorazí na koncový bod, u kterého jste na tlačítko klikli, bez ohledu na to, jaké události daný bod naslouchá.

Zabezpečení: ověřování doručení

Každé doručení nese čtyři hlavičky:

Hlavička	Hodnota
X-ChatLab-Signature	sha256=<hex hmac> - podpis HMAC-SHA256 datové části (payloadu)
X-ChatLab-Timestamp	Unixový čas v sekundách, kdy bylo doručení podepsáno
X-ChatLab-Event	Typ události, např. lead.created
X-ChatLab-Delivery	Unikátní ID doručení, shodné s eventId v těle požadavku

Podpis se počítá jako HMAC-SHA256 z řetězce {timestamp}.{rawBody} pomocí tajného klíče vašeho koncového bodu, kde {timestamp} je hodnota hlavičky X-ChatLab-Timestamp a {rawBody} je surové, nezpracované tělo požadavku. Vždy ověřujte oproti surovým bajtům - opětovná serializace zpracovaného JSON změní sekvenci bajtů a poruší podpis.

Pro ochranu před útoky typu replay (opakování požadavku) odmítněte doručení, jejichž X-ChatLab-Timestamp je starší než 5 minut.

Node.js

const crypto = require('crypto');

function verifyChatLabSignature(req, secret) {
    const signature = req.headers['x-chatlab-signature'];
    const timestamp = req.headers['x-chatlab-timestamp'];
    if (!signature || !timestamp) return false;

    // Reject stale deliveries (older than 5 minutes)
    const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
    if (ageSeconds > 300) return false;

    // rawBody must be the raw request body bytes, not re-serialized JSON.
    // With Express: app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }))
    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(timestamp + '.' + req.rawBody)
        .digest('hex');

    const a = Buffer.from(signature);
    const b = Buffer.from(expected);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
}

PHP

<?php
function verifyChatLabSignature(string $secret): bool
{
    $signature = $_SERVER['HTTP_X_CHATLAB_SIGNATURE'] ?? '';
    $timestamp = $_SERVER['HTTP_X_CHATLAB_TIMESTAMP'] ?? '';
    if ($signature === '' || $timestamp === '') {
        return false;
    }

    // Reject stale deliveries (older than 5 minutes)
    if (abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $rawBody = file_get_contents('php://input');
    $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    return hash_equals($expected, $signature);
}

Pokud ověření selže, odpovězte kódem 401 a datovou část zahoďte. Neověřená doručení nikdy nezpracovávejte - kdokoli, kdo zjistí vaši URL adresu, na ni může poslat libovolný JSON přes metodu POST.

Chování při doručování

Než začnete na webhookách stavět, seznamte se s těmito pravidly:

• Odpovídejte rychle. Váš koncový bod musí odpovědět do 3 sekund, jinak se doručení považuje za neúspěšné. Odpovězte stavovým kódem 2xx okamžitě a datovou část zpracujte asynchronně (zařaďte ji do fronty a teprve poté potvrďte) - před odesláním odpovědi neprovádějte žádná volání CRM ani zápisy do databáze.
• Fire-and-forget, nanejvýš jednou. Každá událost má přesně jeden pokus o doručení - neprobíhají žádné opakované pokusy. Pokud je váš koncový bod nedostupný, vyprší časový limit nebo vrátí jiný stav než 2xx, událost je ztracena a nebude znovu doručována. Webhooky slouží jako upozornění, nikoli jako replikované datové úložiště: pokud potřebujete zaručenou úplnost dat, proveďte synchronizaci s Management API nebo s exporty leadů.
• Jistič (circuit breaker). Po 5 po sobě jdoucích neúspěšných doručeních pro daného bota se doručování pro tohoto bota pozastaví na 5 minut. Události, které nastanou během této pauzy, se zahodí a v protokolu doručení se zobrazí záznamy CIRCUIT_OPEN, abyste přesně viděli, kdy a proč byl provoz potlačen. Doručení přeskočená v důsledku sepnutého jističe se nezapočítávají do automatického vypnutí.
• Automatické vypnutí. Kontrola probíhá v okamžiku, kdy doručení selže, nikdy podle časovače. Pokud doručení selže a za posledních 7 dní neproběhlo žádné úspěšné doručení - počítáno od posledního úspěchu, nebo od data vytvoření koncového bodu, pokud nikdy neuspěl - koncový bod se vypne a vy obdržíte e-mailové oznámení. Jediný kód 2xx v libovolném okamžiku tento odpočet vynuluje. Koncový bod, který nepřijímá žádný provoz, se nikdy nevypne, protože na něm nic neselhalo. Jakmile svůj přijímač opravíte, znovu jej povolte v Account settings (Nastavení účtu); počítadlo selhání a časové razítko automatického vypnutí se po opětovném zapnutí vymažou a události zmeškané během doby vypnutí se zpětně nedoplňují.
• 410 Gone. Pokud váš koncový bod odpoví stavovým kódem HTTP 410 Gone, ChatLab jej okamžitě deaktivuje. To můžete využít k programovému vyřazení koncového bodu z provozu na přijímací straně.
• Idempotence. Při běžném provozu se duplicitní doručení neočekávají, ale pokud vaše zpracování musí být striktně idempotentní, provádějte deduplikaci podle eventId (k dispozici také v hlavičce X-ChatLab-Delivery).

Limity

• Až 10 koncových bodů pro webhooky na jeden účet.
• Uchovávání protokolů doručení: 14 dní. Starší záznamy se automaticky mažou.

Související články

• Lead collection (Sběr leadů) - formulář stojící za událostí lead.created
• Human Support Contact form (Kontaktní formulář na lidskou podporu) - formulář stojící za událostí contact_form.submitted
• Live Chat - proces stojící za událostmi live_chat.*
• Conversation rating (Hodnocení konverzace) - palce nahoru/dolů stojící za událostí conversation.rated
• AI Actions (Akce AI) - integrace stojící za událostí ai_action.executed
• Chat API - callbacky widgetu v prohlížeči (klientský protějšek k webhookům)
• Management API - REST API pro správu botů a data o využití