Centru de ajutor
Chat API

Webhookuri

Ultima actualizare:

Prezentare generală a webhookurilor

Webhookurile permit ChatLab să vă notifice sistemele în momentul în care se întâmplă ceva în chatboturile dumneavoastră. În loc să interogați periodic Management API sau să exportați date manual, înregistrați un endpoint HTTPS, iar ChatLab îi trimite o cerere HTTP POST semnată în timp real - atunci când un vizitator lasă un lead, trimite un formular de contact, evaluează o conversație, solicită un operator uman sau când se execută o acțiune AI.

Utilizări tipice:

  • trimiterea noilor leaduri direct în CRM-ul dumneavoastră în secunda în care sunt capturate
  • notificarea echipei dumneavoastră în Slack atunci când un vizitator solicită Live Chat (chat pe viu)
  • transmiterea evaluărilor și a rezumatelor conversațiilor către propriul sistem de analiză
  • monitorizarea execuțiilor de AI action (acțiuni AI) și alertarea în caz de erori

Disponibilitate: webhookurile sunt disponibile începând cu planul STANDARD (funcționalitate: Webhooks).

Unde se configurează: în aplicația de administrare, deschideți Account settings -> Webhooks (Setări cont -> Webhookuri - chiar lângă secțiunea Management API). Webhookurile sunt la nivel de cont - un singur endpoint poate primi evenimente de la toate boturile dumneavoastră sau de la un subset filtrat.

Configurarea unui endpoint

  1. Deschideți Account settings -> Webhooks (Setări cont -> Webhookuri) și faceți clic pe Create endpoint (Creare endpoint).
  2. Completați formularul pentru endpoint:
    • Name (Nume) - o etichetă pentru referința dumneavoastră, de exemplu „Sincronizare CRM” sau „Alerte Slack”.
    • URL - adresa HTTPS către care ChatLab va trimite evenimentele prin POST.
    • Events (Evenimente) - selectați ce tipuri de evenimente primește acest endpoint (consultați catalogul de mai jos). Selectați doar ceea ce aveți nevoie; evenimentele cu volum mare, cum ar fi ai_action.executed, pot genera mult trafic.
    • Bot filter (Filtru bot) (opțional) - restricționați endpointul la anumiți boți. Lăsați necompletat pentru a primi evenimente de la toți boții din contul dumneavoastră.
    • Custom form filter (Filtru formular personalizat) (opțional) - direcționează trimiterile unui anumit formular personalizat către acest endpoint. Acesta restrânge doar evenimentul custom_form.submitted; orice alt eveniment la care sunteți abonat (leaduri, solicitări de contact, conversații, Live Chat, acțiuni AI) este livrat indiferent de această setare.
  3. Trimiteți. Secretul (secret) endpointului este afișat o singură dată în fereastra de confirmare - copiați-l acum și păstrați-l în siguranță. Veți avea nevoie de el pentru a verifica semnăturile (consultați Securitate mai jos). Textul în clar nu mai poate fi recuperat ulterior.

Fiecare endpoint dispune, de asemenea, de:

  • Comutator activare/dezactivare - întrerupeți livrările fără a șterge endpointul. Endpointurile dezactivate ignoră silențios evenimentele (acestea nu sunt puse în coadă pentru mai târziu).
  • Send sample event (Trimitere eveniment demonstrativ) - livrează o cerere de test semnată către URL-ul dumneavoastră, astfel încât să puteți verifica receptorul cap-la-cap. Puteți alege tipul de eveniment și puteți edita valorile demonstrative înainte de trimitere, pentru ca handlerul dumneavoastră să vadă date realiste. Testul sosește ca o livrare obișnuită, având eventType corespunzător selecției dumneavoastră (sau ca webhook.test pentru o simplă verificare a conectivității).
  • Roll secret (Generare secret nou) - generează un nou secret și îl invalidează pe cel vechi. Folosiți această opțiune dacă secretul a fost compromis. Noul secret este afișat, de asemenea, o singură dată. Actualizați-vă receptorul înainte de a rula această acțiune, altfel livrările vor eșua la verificarea semnăturii în sistemul dumneavoastră.
  • Delivery log (Jurnal de livrări) - o listă per endpoint cu livrările recente, incluzând marcajul temporal, tipul de eveniment, codul de stare HTTP returnat de serverul dumneavoastră și timpul de răspuns. Livrările eșuate și pauzele de tip circuit breaker sunt vizibile aici. Jurnalul este păstrat timp de 14 zile.

Învelișul evenimentului (event envelope)

Fiecare livrare este o cerere HTTP POST cu Content-Type: application/json. Corpul cererii conține întotdeauna aceeași structură de bază; obiectul data este specific fiecărui tip de eveniment:

{
  "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 - identificator unic per eveniment. Folosiți-l pentru deduplicare dacă procesarea dumneavoastră trebuie să fie idempotentă.
  • eventType - unul dintre tipurile documentate mai jos; trimis, de asemenea, în antetul X-ChatLab-Event.
  • timestamp - ora în format ISO 8601 UTC la care a avut loc evenimentul.
  • botId / botName - botul căruia îi aparține evenimentul.
  • conversationId / sessionId - contextul conversației, dacă este cazul.

Catalog de evenimente

lead.created

Se declanșează atunci când un vizitator trimite datele sale de contact - prin intermediul formularului de colectare a leadurilor, al formularului preliminar de Live Chat sau al unui formular personalizat utilizat pentru colectarea de leaduri.

{
  "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 - modul în care au fost capturate datele de contact: LEAD_COLLECTION_FORM (formular de colectare a leadurilor), LIVE_CHAT_FORM (formular preliminar de Live Chat), CONVERSATION (AI-ul a preluat datele în timpul conversației), ADMIN_DATA_UPDATE sau UPDATE_CLIENT_CONTEXT (editate în ChatLab). Trimiterile formularului de asistență umană nu declanșează niciodată acest eveniment - ele declanșează în schimb contact_form.submitted.
  • email, name, phone - datele de contact asociate înregistrării leadului.
  • Când este utilizat un formular personalizat pentru colectarea leadurilor, fiecare câmp definit în acel formular este inclus în fields, în ordinea din formular, iar formCodeName / formName identifică formularul. În cazul formularului clasic de leaduri, ambele sunt null, iar fields este un array gol.
  • Fiecare intrare din fields este de forma {name, value, type}. name este denumirea tehnică a câmpului, stabilă la modificările etichetelor - folosiți-o pentru maparea în CRM-ul dumneavoastră.
  • Pentru câmpurile multichoice, value este un array cu opțiunile selectate. Câmpurile de tip checkbox sunt intrări individuale cu valori "true" / "false".
  • Pentru câmpurile file, value este un link de descărcare către fișierul încărcat; webhookul nu conține niciodată conținutul efectiv al fișierului.
  • pageUrl - pagina pe care se afla vizitatorul în momentul trimiterii.

contact_form.submitted

Se declanșează atunci când un vizitator trimite formularul de contact pentru asistență umană sau un formular personalizat utilizat pentru contact uman.

{
  "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 lăsată de vizitator și cea la care echipa dumneavoastră de asistență ar trebui să răspundă.
  • source - CUSTOM_FORM atunci când formularul de contact folosește un formular personalizat, CONTACT_FORM pentru cel integrat.
  • formCodeName / formName - identifică formularul personalizat asociat cererii; ambele sunt null pentru formularul integrat.
  • Când este utilizat un formular personalizat, fiecare câmp definit în acel formular este inclus în fields (același format {name, value, type} ca la lead.created). În cazul formularului integrat de contact, sunt completate doar email și message, fields este un array gol, iar identificatorii formularului sunt null.
  • message - câmpul de mesaj mapat sau toate valorile completate concatenate, în cazul în care formularul nu definește un câmp de mesaj.

custom_form.submitted

Se declanșează la fiecare trimitere a unui formular personalizat, indiferent de scopul acestuia. Rețineți că formularele al căror scop este colectarea de leaduri sau contactul uman declanșează de asemenea evenimentul dedicat lead.created / contact_form.submitted - abonați-vă la unul sau la celălalt în funcție de perspectiva dorită (generală sau specializată) și efectuați deduplicarea după conversationId + timestamp dacă vă abonați la ambele.

{
  "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 - numele tehnic stabil al formularului, care nu se schimbă dacă redenumiți formularul; folosiți-l pentru a direcționa trimiterile în propriul sistem. formName este denumirea afișată vizitatorilor.
  • fields utilizează aceleași intrări {name, value, type} ca la lead.created: valorile cu selecție multiplă sunt array-uri, iar valorile de tip fișier sunt linkuri de descărcare.
  • purpose - STANDALONE, LEAD_COLLECTION sau HUMAN_CONTACT, în funcție de modul în care formularul este asociat în chatbot.

conversation.started

Se declanșează atunci când un vizitator trimite primul mesaj al unei conversații noi.

{
  "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 - textul exact al primului mesaj trimis de vizitator. null dacă conversația a fost deschisă fără conținut textual.
  • chatSource - canalul pe care a sosit conversația: WIDGET, WHATSAPP, MESSENGER, VOICE, VOICE_PHONE, API, BOOKING, AIRBNB sau IDOBOOKING.
  • byAdmin - true atunci când conversația provine din previzualizarea chatbotului din panoul de administrare ChatLab și nu de la un vizitator real. Folosiți această proprietate pentru a exclude propriile teste din CRM.
  • countryCode - codul de țară ISO determinat pe baza adresei IP a vizitatorului; null dacă nu a putut fi stabilit.
  • ipAddress - adresa IP a vizitatorului, așa cum a fost detectată de ChatLab; null dacă nu este disponibilă. Tratați-o ca date cu caracter personal în conformitate cu GDPR și stocați-o doar dacă aveți un temei legal.

conversation.rated

Se declanșează atunci când un vizitator evaluează răspunsul unui bot cu apreciere pozitivă sau negativă (consultați Evaluarea conversațiilor).

{
  "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 sau NEGATIVE. Resetarea unei evaluări nu declanșează evenimentul, așadar nu veți primi niciodată o valoare neutră.

conversation.summarized

Se declanșează atunci când ChatLab generează rezumatul unei conversații finalizate.

{
  "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 - textul rezumatului generat. Rezumatele sunt generate la câteva minute după ce conversația devine inactivă, așadar acest eveniment sosește mai târziu decât restul evenimentelor legate de conversație.
  • language - codul ISO al limbii în care a fost redactat rezumatul, corespunzător limbii conversației.

client.summarized

Se declanșează atunci când ChatLab actualizează profilul AI al unui client. Profilul este reconstruit pe baza profilului anterior plus rezumatul conversației tocmai încheiate, astfel încât acest eveniment urmează după conversation.summarized pentru aceeași conversație. Clienții sunt identificați prin adresa de e-mail, motiv pentru care adresa este repetată la nivelul principal din 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 - identificatorul utilizat pentru corelarea clientului în propriul CRM. Este null pentru vizitatorii anonimi care nu au lăsat niciodată o adresă, iar evenimentul se declanșează în continuare pentru aceștia - ignorați aceste livrări dacă integrarea dumneavoastră depinde de adresa de e-mail.
  • client - înregistrarea de contact pe care ChatLab o deține pentru această persoană: email, name, phone, countryCode și ipAddress. Fiecare cheie este întotdeauna prezentă; valorile necunoscute sunt null.
  • clientSummary - textul complet al profilului ca text simplu, nu o diferență (diff). Acesta înlocuiește rezumatul precedent în totalitate, așadar stocați-l prin suprascriere, nu prin adăugare la final.
  • Profilul este reconstruit doar pentru boții care au activată opțiunea chat memory (memorie conversații) și doar pentru conversațiile care au fost inactive suficient timp pentru a fi rezumate - așteptați-vă ca acest eveniment să sosească la câteva minute după încheierea conversației, nu imediat.

live_chat.requested

Se declanșează atunci când AI-ul transferă conversația către Live Chat (chat pe viu), fie pentru că vizitatorul a solicitat un operator uman, fie pentru că botul a decis că este necesară intervenția umană.

{
  "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 - în prezent este întotdeauna AI, deoarece transferul este inițiat întotdeauna de acțiunea de chat pe viu a botului, inclusiv atunci când vizitatorul îl solicită explicit în text. Tratați această valoare ca pe un enum deschis: gestionați valorile necunoscute în loc să impuneți condiția strictă AI.
  • Evenimentul indică faptul că transferul a fost solicitat, nu că un operator a preluat deja conversația. Așteptați evenimentul live_chat.started pentru confirmarea preluării.

live_chat.started

Se declanșează atunci când un operator intervine și sesiunea de Live Chat începe efectiv.

{
  "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 este lăsat gol intenționat. Toate informațiile necesare se află în structura de bază: botId identifică chatbotul, iar conversationId / sessionId leagă evenimentul de conversația pentru care ați primit deja live_chat.requested.

live_chat.ended

Se declanșează atunci când sesiunea de Live Chat se încheie.

{
  "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 - durata participării operatorului în conversație, contorizată din momentul începerii sesiunii. Câmpul este omis în situațiile rare în care o sesiune se încheie fără să fi început vreodată.

ai_action.executed

Se declanșează de fiecare dată când botul execută o acțiune AI action - un apel către o integrare gestionată sau o funcție API personalizată. Acesta este un eveniment cu volum ridicat: un bot activ de e-commerce poate executa sute de acțiuni pe zi, iar o singură replică a vizitatorului poate declanșa mai multe. Abonați-vă la acesta pe un endpoint dedicat sau asigurați-vă că receptorul dumneavoastră poate prelua acest volum.

{
  "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 - numele acțiunii executate, așa cum o vede AI-ul, de exemplu search_products pentru o integrare gestionată sau numele pe care l-ați configurat pentru o acțiune API personalizată.
  • status - SUCCESS sau ERROR.
  • durationMs - durata de execuție a acțiunii, în milisecunde. Util pentru identificarea unei integrări lente înainte ca vizitatorii să se plângă de aceasta.
  • errorMessage - motivul eșecului, completat doar atunci când status este ERROR; în rest, null.

webhook.test

Trimis prin intermediul butonului Send sample event (Trimitere eveniment demonstrativ) atunci când efectuați o simplă verificare a conectivității. Este semnat exact ca un eveniment real.

{
  "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 - text fix, întotdeauna identic. Câmpurile din structura de bază conțin valori demonstrative, prin urmare nu tratați niciodată o livrare webhook.test drept date reale.
  • Acesta este singurul tip de eveniment la care nu vă puteți abona în cadrul unui endpoint: este trimis la cerere din panoul de administrare și ajunge întotdeauna la endpointul pe care ați făcut clic, indiferent de evenimentele pe care acesta le ascultă.

Securitate: verificarea livrărilor

Fiecare livrare include patru headere:

Header Valoare
X-ChatLab-Signature sha256=<hex hmac> - semnătura HMAC-SHA256 a sarcinii utile
X-ChatLab-Timestamp Timpul Unix în secunde la momentul semnării livrării
X-ChatLab-Event Tipul evenimentului, de ex. lead.created
X-ChatLab-Delivery ID unic de livrare, identic cu eventId din corpul cererii

Semnătura este calculată ca HMAC-SHA256 pe șirul {timestamp}.{rawBody} folosind cheia secretă a endpoint-ului dumneavoastră, unde {timestamp} reprezintă valoarea din X-ChatLab-Timestamp, iar {rawBody} este corpul brut, neprocesat, al cererii. Verificați întotdeauna pe baza octeților bruți - reserializarea JSON-ului parsat va modifica secvența de octeți și va invalida semnătura.

Pentru a vă proteja împotriva atacurilor de tip replay, respingeți livrările al căror X-ChatLab-Timestamp este mai vechi de 5 minute.

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

Dacă verificarea eșuează, răspundeți cu 401 și ignorați sarcina utilă. Nu procesați niciodată livrări neverificate - oricine descoperă adresa URL poate trimite cereri POST cu date JSON arbitrare către aceasta.

Comportamentul livrării

Înțelegeți aceste garanții înainte de a construi pe baza webhook-urilor:

  • Răspundeți rapid. Endpoint-ul dumneavoastră trebuie să răspundă în cel mult 3 secunde, altfel livrarea este considerată eșuată. Răspundeți imediat cu 2xx și procesați datele în mod asincron (introduceți-le într-o coadă, apoi confirmați primirea) - nu efectuați apeluri CRM sau scrieri în baza de date înainte de a trimite răspunsul.
  • Fire-and-forget, cel mult o dată (at-most-once). Fiecare eveniment primește exact o încercare de livrare - nu există reîncercări. Dacă endpoint-ul dumneavoastră este indisponibil, expiră (timeout) sau returnează un status non-2xx, acel eveniment este pierdut și nu va fi relivrat. Webhook-urile sunt notificări, nu un depozit de date replicat: atunci când aveți nevoie de exhaustivitate garantată, reconciliați datele cu Management API sau cu exporturile de lead-uri.
  • Circuit breaker. După 5 livrări eșuate consecutive pentru un bot, livrările pentru acel bot sunt întrerupte timp de 5 minute. Evenimentele care au loc în timpul acestei pauze sunt eliminate, iar jurnalul de livrări afișează intrări de tip CIRCUIT_OPEN, astfel încât să puteți vedea exact când și de ce a fost oprit traficul. Livrările omise din cauza unui circuit deschis nu sunt luate în calcul pentru dezactivarea automată.
  • Dezactivare automată. Verificarea are loc în momentul în care o livrare eșuează, niciodată pe baza unui cronometru. Dacă o livrare eșuează și nu a existat nicio livrare reușită timp de 7 zile - perioadă calculată de la ultima reușită sau de la data creării endpoint-ului, dacă nu a avut nicio livrare reușită - endpoint-ul este dezactivat și primiți o notificare prin e-mail. Un singur răspuns 2xx în orice moment resetează acest interval. Un endpoint care nu primește trafic nu este niciodată dezactivat, deoarece nimic nu eșuează. Reactivați-l din Account settings (Setările contului) după ce ați remediat sistemul receptor; contorul de eșecuri și marcajul de dezactivare automată sunt șterse la reactivare, iar evenimentele pierdute în perioada de inactivitate nu sunt recuperate.
  • 410 Gone. Dacă endpoint-ul dumneavoastră răspunde cu HTTP 410 Gone, ChatLab îl dezactivează imediat. Utilizați acest cod pentru a scoate din uz un endpoint în mod programatic, direct de pe serverul receptor.
  • Idempotență. Livrările duplicate nu sunt preconizate în condiții normale de funcționare, dar dacă logica de procesare trebuie să fie strict idempotentă, efectuați deduplicarea după eventId (disponibil și în headerul X-ChatLab-Delivery).

Limite

  • Până la 10 endpoint-uri webhook per cont.
  • Păstrarea jurnalului de livrări: 14 zile. Intrările mai vechi sunt eliminate automat.

Articole asociate

  • Lead collection (Colectarea de lead-uri) - formularul din spatele lead.created
  • Human Support Contact form (Formular de contact pentru asistență umană) - formularul din spatele contact_form.submitted
  • Live Chat - fluxul din spatele evenimentelor live_chat.*
  • Conversation rating (Evaluarea conversației) - aprecierile pozitive/negative (thumbs up/down) din spatele conversation.rated
  • AI Actions (Acțiuni AI) - integrările din spatele ai_action.executed
  • Chat API - funcții callback pentru widgetul din browser (echivalentul pe partea de client al webhook-urilor)
  • Management API - API REST pentru administrarea boților și a datelor de utilizare
Căutați în toate articoleleÎntrebați agentul