Centrum pomoci
Chat API

Webhooks

Posledná aktualizácia:

Prehľad webhookov

Webhooky umožňujú aplikácii ChatLab informovať vaše systémy v momente, keď sa v chatbotoch niečo stane. Namiesto dopytovania Management API alebo manuálneho exportu dát zaregistrujete HTTPS koncový bod a ChatLab naň v reálnom čase odošle podpísanú HTTP POST požiadavku - keď návštevník zanechá lead, odošle kontaktný formulár, ohodnotí konverzáciu, vyžiada si operátora alebo keď sa vykoná akcia AI.

Typické využitie:

  • odosielanie nových leadov priamo do CRM v sekunde ich zachytenia
  • upozornenie tímu v aplikácii Slack, keď návštevník požiada o live chat (živý chat)
  • prenos hodnotení a zhrnutí konverzácií do vlastnej analytiky
  • monitorovanie vykonávania AI akcie a upozornenia na chyby

Dostupnosť: webhooky sú k dispozícii od balíka Standard vyššie (funkcia: Webhooks).

Kde ich nakonfigurovať: v administrátorskej aplikácii otvorte Account settings -> Webhooks (Nastavenia účtu -> Webhooky - hneď vedľa sekcie Management API). Webhooky fungujú na úrovni účtu - jeden koncový bod môže prijímať udalosti zo všetkých vašich botov alebo z vyfiltrovanej podmnožiny.

Nastavenie koncového bodu

  1. Otvorte Account settings -> Webhooks a kliknite na Create endpoint (Vytvoriť koncový bod).
  2. Vyplňte formulár koncového bodu:
    • Name (Názov) - označenie pre vašu orientáciu, napr. „CRM sync" alebo „Slack alerts".
    • URL - HTTPS adresa, na ktorú bude ChatLab odosielať udalosti cez POST.
    • Events (Udalosti) - vyberte typy udalostí, ktoré má tento koncový bod prijímať (pozrite si katalóg nižšie). Vyberajte iba to, čo naozaj potrebujete; udalosti s vysokým objemom ako ai_action.executed môžu generovať veľkú prevádzku.
    • Bot filter (Filter botov) (voliteľné) - obmedzte koncový bod na konkrétnych botov. Ak ho necháte prázdny, budete prijímať udalosti zo všetkých botov vo svojom účte.
    • Custom form filter (Filter vlastných formulárov) (voliteľné) - smeruje odoslania jedného vlastného formulára na tento koncový bod. Zúži iba udalosť custom_form.submitted; každá ďalšia odoberaná udalosť (leady, požiadavky na kontakt, konverzácie, live chat, akcie AI) sa doručuje bez ohľadu na toto nastavenie.
  3. Odošlite. Secret (tajný kľúč) koncového bodu sa zobrazí presne raz v potvrdzovacom dialógu - skopírujte si ho hneď a bezpečne uložte. Budete ho potrebovať na overenie podpisov (pozrite časť Bezpečnosť nižšie). V čitateľnej podobe ho neskôr už nemožno získať.

Každý koncový bod má tiež:

  • Prepínač Enable/disable (Zapnúť/vypnúť) - pozastaví doručovanie bez odstránenia koncového bodu. Vypnuté koncové body udalosti ticho zahadzujú (nezaraďujú sa do frontu na neskôr).
  • Send sample event (Odoslať ukážkovú udalosť) - doručí na vašu URL podpísanú testovaciu požiadavku, aby ste si overili prijímač od začiatku do konca. Pred odoslaním si môžete vybrať typ udalosti a upraviť vzorové hodnoty, aby váš obslužný program videl realistické dáta. Test dorazí ako bežné doručenie s parametrom eventType zodpovedajúcim vášmu výberu (alebo ako webhook.test pre jednoduchú kontrolu spojenia).
  • Roll secret (Obnoviť tajný kľúč) - vygeneruje nový tajný kľúč a zneplatní pôvodný. Použite to, ak mohlo dôjsť k úniku tajného kľúča. Nový kľúč sa znova zobrazí iba raz. Pred obnovením aktualizujte svoj prijímač, inak doručenia na vašej strane zlyhajú pri overovaní podpisu.
  • Delivery log (Záznam doručovania) - zoznam nedávnych doručení pre daný koncový bod s časovou pečiatkou, typom udalosti, HTTP stavom vráteným vaším serverom a časom odozvy. Sú tu viditeľné neúspešné doručenia aj pozastavenia spôsobené mechanizmom circuit breaker. Záznam sa uchováva 14 dní.

Obálka udalosti

Každé doručenie je požiadavka HTTP POST s hlavičkou Content-Type: application/json. Telo má vždy rovnakú obálku; objekt data je špecifický pre daný typ udalosti:

{
  "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 - jedinečný identifikátor udalosti. Použite ho na deduplikáciu, ak vaše spracovanie musí byť idempotentné.
  • eventType - jeden z nižšie popísaných typov; odosiela sa aj v hlavičke X-ChatLab-Event.
  • timestamp - čas vzniku udalosti v UTC vo formáte ISO 8601.
  • botId / botName - bot, ku ktorému udalosť patrí.
  • conversationId / sessionId - kontext konverzácie, ak je relevantný.

Katalóg udalostí

lead.created

Spúšťa sa, keď návštevník odošle svoje kontaktné údaje - cez formulár na zber leadov, úvodný formulár pred live chatom alebo vlastný formulár určený na zber leadov.

{
  "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 - spôsob zachytenia kontaktných údajov: LEAD_COLLECTION_FORM (formulár na zber leadov), LIVE_CHAT_FORM (úvodný formulár pred live chatom), CONVERSATION (AI získala údaje počas chatu), ADMIN_DATA_UPDATE alebo UPDATE_CLIENT_CONTEXT (upravené na strane ChatLabu). Odoslania formulára podpory človekom túto udalosť nikdy nespúšťajú - namiesto toho spúšťajú contact_form.submitted.
  • email, name, phone - kontaktné údaje namapované na záznam leadu.
  • Ak sa na zber leadov použije vlastný formulár, v poli fields sú zahrnuté všetky polia definované v tomto formulári v poradí podľa formulára, pričom formCodeName / formName identifikujú daný formulár. Pri klasickom formulári na leady sú obe hodnoty null a pole fields je prázdne.
  • Každá položka v fields má tvar {name, value, type}. name je technický názov poľa, ktorý sa nemení ani pri úpravách štítkov - použite ho na mapovanie do vášho CRM.
  • Pri poliach typu multichoice je value pole (array) vybratých možností. Začiarkavacie polia (checkbox) sú samostatné položky s hodnotami "true" / "false".
  • Pri poliach typu file je value odkaz na stiahnutie nahraného súboru; webhook nikdy neprenáša samotný obsah súboru.
  • pageUrl - stránka, na ktorej sa návštevník nachádzal pri odoslaní.

contact_form.submitted

Spúšťa sa, keď návštevník odošle kontaktný formulár pre podporu človekom alebo vlastný formulár slúžiaci na kontaktovanie človeka.

{
  "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, ktorú návštevník zanechal a na ktorú by mal váš tím podpory odpovedať.
  • source - CUSTOM_FORM, ak je kontaktný formulár postavený na vlastnom formulári, alebo CONTACT_FORM pri vstavanom formulári.
  • formCodeName / formName - identifikujú vlastný formulár stojaci za požiadavkou; pri vstavanom formulári sú obe hodnoty null.
  • Keď sa použije vlastný formulár, každé pole definované v tomto formulári je zahrnuté v fields (rovnaký formát {name, value, type} ako pri lead.created). Pri vstavanom kontaktnom formulári sú vyplnené iba email a message, fields je prázdne pole a identifikátory formulára sú null.
  • message - namapované pole správy alebo všetky vyplnené hodnoty spojené dohromady, ak formulár nemá samostatné pole pre správu.

custom_form.submitted

Spúšťa sa pri každom odoslaní vlastného formulára bez ohľadu na jeho účel. Upozorňujeme, že formuláre, ktorých účelom je zber leadov alebo kontaktovanie človeka, spúšťajú tiež svoju vyhradenú udalosť lead.created / contact_form.submitted - prihláste sa na odber jednej alebo druhej podľa toho, či chcete všeobecný alebo špecializovaný pohľad, a ak odoberáte obe, deduplikujte ich pomocou 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 - stabilný technický názov formulára, ktorý sa pri premenovaní formulára nemení; použite ho na smerovanie odoslaných dát vo vlastnom systéme. formName je zobrazovaný názov pre návštevníkov.
  • fields používa rovnaké položky {name, value, type} ako lead.created: hodnoty multichoice sú polia (arrays), hodnoty file sú odkazy na stiahnutie.
  • purpose - STANDALONE, LEAD_COLLECTION alebo HUMAN_CONTACT podľa toho, ako je formulár napojený na chatbota.

conversation.started

Spúšťa sa, keď návštevník odošle prvú správu novej konverzácie.

{
  "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 - presný text úvodnej správy návštevníka. null, ak bola konverzácia otvorená bez obsahu správy.
  • chatSource - kanál, z ktorého konverzácia prišla: WIDGET, WHATSAPP, MESSENGER, VOICE, VOICE_PHONE, API, BOOKING, AIRBNB alebo IDOBOOKING.
  • byAdmin - true, ak konverzácia pochádza z náhľadu chatbota v administrátorskom paneli ChatLab namiesto od skutočného návštevníka. Pomáha udržať vlastné testovacie chaty mimo vášho CRM.
  • countryCode - kód krajiny ISO odvodený z IP adresy návštevníka, null, ak sa ho nepodarilo určiť.
  • ipAddress - IP adresa návštevníka zaznamenaná službou ChatLab, null, ak nie je dostupná. Podľa nariadenia GDPR s ňou zaobchádzajte ako s osobným údajom a ukladajte ju iba vtedy, ak na to máte právny základ.

conversation.rated

Spúšťa sa, keď návštevník ohodnotí odpoveď bota palcom hore alebo dole (pozrite si Hodnotenie konverzácií).

{
  "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 alebo NEGATIVE. Zrušenie hodnotenia túto udalosť nespúšťa, takže neutrálnu hodnotu nikdy nedostanete.

conversation.summarized

Spúšťa sa, keď ChatLab vygeneruje zhrnutie ukončenej konverzácie.

{
  "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 - text vygenerovaného zhrnutia. Zhrnutia sa vytvárajú niekoľko minút po tom, čo konverzácia prestane byť aktívna, takže táto udalosť dorazí neskôr ako ostatné udalosti konverzácie.
  • language - ISO kód jazyka, v ktorom bolo zhrnutie napísané (zodpovedá jazyku konverzácie).

client.summarized

Spúšťa sa, keď ChatLab aktualizuje profil klienta vytvorený pomocou AI. Profil sa zostavuje z predchádzajúceho profilu a zhrnutia práve ukončenej konverzácie, takže táto udalosť nasleduje po conversation.summarized pre rovnakú konverzáciu. Klienti sa identifikujú e-mailom, a preto sa adresa opakuje na najvyššej ú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 na spárovanie klienta s vaším vlastným CRM. Pri anonymných návštevníkoch, ktorí nikdy nezanechali adresu, má hodnotu null, pričom udalosť sa pre nich stále spúšťa - tieto doručenia preskočte, ak je vaša integrácia naviazaná na e-mail.
  • client - kontaktný záznam, ktorý ChatLab o tejto osobe uchováva: email, name, phone, countryCode a ipAddress. Každý kľúč je vždy prítomný; neznáme hodnoty sú null.
  • clientSummary - celý text profilu ako čistý text, nejde o rozdiel (diff). Nahrádza pôvodné zhrnutie, preto ho ukladajte prepísaním, nie pripájaním na koniec.
  • Profil sa obnovuje iba pri botoch so zapnutou pamäťou chatu a len pri konverzáciách, ktoré boli neaktívne dostatočne dlho na vytvorenie zhrnutia - túto udalosť očakávajte niekoľko minút po skončení konverzácie, nie okamžite.

live_chat.requested

Spúšťa sa, keď AI odovzdá konverzáciu do live chatu, buď preto, že návštevník požiadal o človeka, alebo preto, že bot vyhodnotil zásah človeka ako potrebný.

{
  "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 súčasnosti vždy AI, pretože odovzdanie vždy iniciuje akcia live chatu bota, a to aj vtedy, keď o to návštevník požiada vlastnými slovami. Považujte to za otvorený enum: ošetrite aj neznáme hodnoty namiesto striktného overovania hodnoty AI.
  • Udalosť hovorí o tom, že bolo odovzdanie vyžiadané, nie že ho už operátor prevzal. Na to počkajte na udalosť live_chat.started.

live_chat.started

Spúšťa sa, keď sa pripojí operátor a relácia živého chatu sa skutočne 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": {}
}
  • data je zámerne prázdne. Všetko potrebné je v obálke: botId identifikuje chatbota a conversationId / sessionId prepájajú udalosť s konverzáciou, pre ktorú ste už prijali live_chat.requested.

live_chat.ended

Spúšťa sa po ukončení relácie živého chatu.

{
  "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 - čas v sekundách, počas ktorého bol operátor v konverzácii, počítaný od okamihu začiatku relácie. Pole sa vynecháva v zriedkavom prípade, keď sa relácia skončí bez toho, aby bola vôbec spustená.

ai_action.executed

Spúšťa sa pri každom vykonaní AI akcie botom - pri volaní spravovanej integrácie alebo vlastnej funkcie API. Ide o vysokoobjemovú udalosť: aktívny e-commerce bot môže vykonať stovky akcií denne a jedna odpoveď návštevníka môže spustiť hneď niekoľko akcií. Prihláste sa na jej odber na vyhradenom koncovom bode alebo sa uistite, že váš prijímač takýto objem zvládne spracovať.

{
  "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ázov vykonanej akcie tak, ako ho vidí AI, napríklad search_products pri spravovanej integrácii alebo názov, ktorý ste dali vlastnej API akcii.
  • status - SUCCESS alebo ERROR.
  • durationMs - čas trvania akcie v milisekundách. Užitočné na odhalenie pomalej integrácie skôr, ako sa na ňu začnú sťažovať návštevníci.
  • errorMessage - dôvod zlyhania, vyplnený iba vtedy, keď má status hodnotu ERROR; inak má hodnotu null.

webhook.test

Odosiela sa tlačidlom Send sample event pri spustení jednoduchej kontroly spojenia. Je podpísaná presne ako skutočná udalosť.

{
  "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 - fixný text, vždy rovnaký. Polia obálky nesú vzorové hodnoty, preto doručenie webhook.test nikdy nepovažujte za skutočné dáta.
  • Ide o jediný typ udalosti, na ktorý sa na koncovom bode nedá prihlásiť: odosiela sa na požiadanie z administrátorského panelu a vždy dorazí na koncový bod, na ktorý ste klikli, bez ohľadu na to, aké udalosti počúva.

Bezpečnosť: overovanie doručení

Každé doručenie obsahuje štyri hlavičky:

Hlavička Hodnota
X-ChatLab-Signature sha256=<hex hmac> - HMAC-SHA256 podpis payloadu
X-ChatLab-Timestamp Unixový čas v sekundách, kedy bolo doručenie podpísané
X-ChatLab-Event Typ udalosti, napr. lead.created
X-ChatLab-Delivery Jedinečné ID doručenia, zhodné s eventId v tele

Podpis sa počíta ako HMAC-SHA256 z reťazca {timestamp}.{rawBody} pomocou tajného kľúča vášho endpointu, kde {timestamp} je hodnota X-ChatLab-Timestamp a {rawBody} je surové, nespracované telo požiadavky. Vždy overujte voči surovým bajtom - opätovná serializácia naparsovaného JSON zmení postupnosť bajtov a zneplatní podpis.

Na ochranu pred replay útokmi odmietajte doručenia, ktorých X-ChatLab-Timestamp je starší ako 5 minút.

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);
}

Ak overenie zlyhá, odpovedzte stavom 401 a payload zahoďte. Nikdy nespracovávajte neoverené doručenia - ktokoľvek, kto zistí vašu URL, na ňu môže poslať ľubovoľný JSON cez POST.

Správanie doručovania

Pred budovaním riešení na webhookoch vezmite do úvahy tieto garancie:

  • Odpovedajte rýchlo. Váš endpoint musí odpovedať do 3 sekúnd, inak sa doručenie považuje za neúspešné. Odpovedzte stavom 2xx okamžite a payload spracujte asynchrónne (zaradte ho do frontu a až potom potvrďte) - pred odoslaním odpovede nevykonávajte volania do CRM ani zápisy do databázy.
  • Fire-and-forget, najviac raz. Každá udalosť má presne jeden pokus o doručenie - žiadne opakované pokusy neexistujú. Ak je váš endpoint nedostupný, vyprší mu časový limit alebo vráti iný stav než 2xx, daná udalosť je stratená a znova sa nedoručí. Webhooky sú notifikácie, nie replikované dátové úložisko: ak potrebujete zaručenú úplnosť, zosúlaďte dáta cez Management API alebo exporty leadov.
  • Circuit breaker. Po 5 po sebe idúcich neúspešných doručeniach pre daného bota sa doručovanie pre tohto bota pozastaví na 5 minút. Udalosti, ktoré nastanú počas tejto pauzy, sa zahodia a v protokole doručení sa zobrazia záznamy CIRCUIT_OPEN, aby ste presne videli, kedy a prečo bola prevádzka potlačená. Doručenia preskočené z dôvodu otvoreného okruhu sa nezapočítavajú do automatického vypnutia.
  • Automatické vypnutie. Kontrola prebieha v okamihu zlyhania doručenia, nikdy nie na základe časovača. Ak doručenie zlyhá a počas 7 dní nedošlo k žiadnemu úspešnému doručeniu - počítané od posledného úspechu, alebo od dátumu vytvorenia endpointu, ak ešte nikdy neuspel - endpoint sa vypne a dostanete e-mailové upozornenie. Jediný kód 2xx kedykoľvek tento odpočet resetuje. Endpoint, na ktorý nechodí žiadna prevádzka, sa nikdy nevypne, pretože pri ňom nič nezlyháva. Keď svoj prijímač opravíte, znova ho aktivujte v Account settings (Nastavenia účtu); počítadlo zlyhaní a časová pečiatka automatického vypnutia sa pri opätovnom zapnutí vymažú a udalosti zmeškané počas neaktivity sa spätne nedopĺňajú.
  • 410 Gone. Ak váš endpoint odpovie kódom HTTP 410 Gone, ChatLab ho okamžite vypne. Toto využite na programové vyradenie endpointu z prevádzky na strane príjemcu.
  • Idempotencia. Pri bežnej prevádzke sa duplicitné doručenia neočakávajú, no ak vaše spracovanie musí byť striktne idempotentné, deduplikujte podľa eventId (dostupné aj v hlavičke X-ChatLab-Delivery).

Limity

  • Maximálne 10 webhook endpointov na účet.
  • Doba uchovávania protokolu doručení: 14 dní. Staršie záznamy sa odstraňujú automaticky.

Súvisiace články

Prehľadávať všetky článkySpýtajte sa agenta