Abikeskus
Chat API

Veebikonksud (Webhooks)

Viimati uuendatud:

Webhookide ülevaade

Webhookid võimaldavad ChatLabil teavitada teie süsteeme kohe, kui teie vestlusrobotites midagi juhtub. Selle asemel et teha päringuid Management API liidesesse või eksportida andmeid käsitsi, registreerite HTTPS-lõpp-punkti ja ChatLab saadab sinna reaalajas allkirjastatud HTTP POST-päringu - näiteks siis, kui külastaja jätab müügivihje (lead), esitab kontaktivormi, hindab vestlust, soovib suhelda inimesega või kui käivitub AI toiming.

Tüüpilised kasutusjuhud:

  • uute müügivihjete saatmine otse oma CRM-i kohe pärast nende kogumist
  • oma meeskonna teavitamine Slackis, kui külastaja soovib Live Chat (reaalajas vestluse) tuge
  • vestluste hinnangute ja kokkuvõtete edastamine oma analüütikatööriistadesse
  • AI toimingute (AI actions) käivitamise jälgimine ja tõrgete korral hoiatuste saamine

Saadavus: teie konto peab sisaldama funktsiooni Webhooks.

Kus seadistada: avage administraatorirakenduses Account settings -> Webhooks (Konto seaded -> Webhookid, mis asub otse Management API jaotise kõrval). Webhookid toimivad konto tasemel - üks lõpp-punkt võib võtta vastu sündmusi kõigilt teie vestlusrobotitelt või ainult ühelt valitud robotilt.

Lõpp-punkti seadistamine

  1. Avage Account settings -> Webhooks (Konto seaded -> Webhookid) ja klõpsake nupul Add endpoint (Lisa lõpp-punkt).
  2. Täitke lõpp-punkti vorm:
    • Name (Nimi) - silt teie enda tarbeks, nt "CRM-i sünkroonimine" või "Slack-teavitused".
    • URL - HTTPS-aadress, kuhu ChatLab sündmusi POST-päringuga saadab.
    • Events (Sündmused) - valige, milliseid sündmustüüpe see lõpp-punkt vastu võtab (vt allpool olevat kataloogi). Valige ainult need, mida vajate; suure mahuga sündmused, nagu ai_action.executed, võivad tekitada palju võrguliiklust.
    • Bot filter (Roboti filter) (valikuline) - valige üks vestlusrobot või All bots (Kõik robotid), et kaasata kõik teie konto robotid.
    • Custom form filter (Kohandatud vormi filter) (valikuline) - suunab ühe kindla kohandatud vormi esitamised sellesse lõpp-punkti. See piirab ainult sündmust custom_form.submitted; kõik teised tellitud sündmused (müügivihjed, kontaktipäringud, vestlused, Live Chat, AI toimingud) edastatakse sellest seadistusest sõltumata.
  3. Kinnitage vorm. Lõpp-punkti salavõtit ehk secret-väärtust kuvatakse õnnestumise dialoogis täpselt üks kord - kopeerige see kohe ja hoidke seda turvaliselt. Vajate seda allkirjade kontrollimiseks (vt jaotist Turvalisus allpool). Lihttekstina ei ole seda hiljem enam võimalik vaadata.

Igal lõpp-punktil on lisaks:

  • Lüliti Enable/disable (Luba/keela) - peatab edastused ilma lõpp-punkti kustutamata. Keelatud lõpp-punktid jätavad sündmused vaikimisi vahele (neid ei panda järjekorda hilisemaks saatmiseks).
  • Send sample event (Saada näidissündmus) - saadab teie URL-ile allkirjastatud testpäringu, et saaksite oma vastuvõtjat otsast lõpuni kontrollida. Saate enne saatmist valida sündmuse tüübi ja muuta näidisväärtusi, et teie töötleja näeks realistlikke andmeid. Test saabub tavapärase edastusena, kus eventType vastab teie valikule (või väärtusega webhook.test lihtsa ühenduvuskontrolli puhul).
  • Roll secret (Uuenda salavõtit) - genereerib uue salavõtme ja muudab vana kehtetuks. Kasutage seda juhul, kui salavõti võib olla lekkinud. Uut salavõtit kuvatakse samuti ainult üks kord. Kontrollitud vahetamiseks peatage lõpp-punkt, uuendage ja kopeerige uus salavõti, värskendage vastuvõtjat, lülitage lõpp-punkt uuesti sisse ning saatke näidissündmus. Peatamise ajal toimunud sündmusi järjekorda ei salvestata. Planeerige see katkestus enne võtme vahetamist ette.
  • Delivery log (Edastuslogi) - lõpp-punkti hiljutiste edastuste loend koos ajatempli, sündmuse tüübi, teie serveri tagastatud HTTP-olekukoodi ja vastuseajaga. Siin kuvatakse ebaõnnestunud edastused ja kaitselüliti (circuit breaker) automaatsed pausid. Logi säilitatakse 14 päeva.

Sündmuse ümbrik (envelope)

Iga edastus on HTTP POST-päring päisega Content-Type: application/json. Päringu kehal on alati sama ümbrikstruktuur; data objekt sõltub konkreetsest sündmuse tüübist:

{
  "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 - sündmuse unikaalne identifikaator. Kasutage seda duplikaatide eemaldamiseks, kui teie töötlemine peab olema idempotentne.
  • eventType - üks allpool kirjeldatud tüüpidest; saadetakse ka päises X-ChatLab-Event.
  • timestamp - ISO 8601 UTC kellaaeg, millal edastusümbrik ette valmistati.
  • botId / botName - vestlusrobot, millele sündmus kuulub.
  • conversationId / sessionId - vestluse kontekst, kui see on kohaldatav.

Sündmuste kataloog

lead.created

Käivitub, kui külastaja esitab oma kontaktandmed - kontaktide kogumise vormi (lead collection form), reaalajas vestluse eelvormi või kohandatud vormi kaudu, mida kasutatakse kontaktide kogumiseks.

{
  "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 - viis, kuidas kontaktandmed koguti: LEAD_COLLECTION_FORM (kontaktide kogumise vorm), LIVE_CHAT_FORM (reaalajas vestluse eelvorm), CONVERSATION (tehisintellekt kogus andmed vestluse käigus), ADMIN_DATA_UPDATE või UPDATE_CLIENT_CONTEXT (muudetud ChatLabi poolel). Klienditoe kontaktivormi esitamised ei käivita seda sündmust kunagi - selle asemel käivitub sündmus contact_form.submitted.
  • email, name, phone - kontakti kirjele vastendatud kontaktandmed.
  • Kui kontaktide kogumiseks kasutatakse kohandatud vormi, kaasatakse iga sellel vormil määratletud väli massiivi fields, vormi järjekorras, ning formCodeName / formName tuvastavad vastava vormi. Klassikalise kontaktide kogumise vormi puhul on mõlemad väärtuseks null ja fields on tühi massiiv.
  • Iga kirje massiivis fields on kujul {name, value, type}. name on välja tehniline nimi, mis jääb siltide muutmisel samaks - kasutage seda oma CRM-i vastendamiseks.
  • Väljade multichoice puhul on value valitud valikute massiiv. Märkeruudu väljad on eraldi kirjed väärtustega "true" / "false".
  • Väljade file puhul on value üleslaaditud faili allalaadimislink; veebikonks (webhook) ei kanna kunagi faili tegelikku sisu.
  • pageUrl - veebileht, kus külastaja andmete esitamise hetkel viibis.

contact_form.submitted

Käivitub, kui külastaja esitab klienditoe kontaktivormi või kohandatud vormi, mida kasutatakse klienditoega ühenduse võtmiseks.

{
  "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 - külastaja sisestatud e-posti aadress, millele teie tugimeeskond peaks vastama.
  • source - CUSTOM_FORM, kui kontaktivormina kasutatakse kohandatud vormi, ja CONTACT_FORM sisseehitatud vormi puhul.
  • formCodeName / formName - tuvastavad päringu taga oleva kohandatud vormi; sisseehitatud vormi puhul on mõlema väärtuseks null.
  • Kohandatud vormi kasutamisel kaasatakse iga sellel määratletud väli massiivi fields (sama vorming {name, value, type} nagu sündmuse lead.created puhul). Sisseehitatud kontaktivormi puhul täidetakse ainult väljad email ja message, fields on tühi massiiv ja vormi identifikaatorid on väärtusega null.
  • message - vastendatud sõnumiväli või kõigi täidetud väärtuste ühendus, kui vormil pole eraldi sõnumivälja määratletud.

custom_form.submitted

Käivitub iga kohandatud vormi esitamisel, olenemata vormi eesmärgist. Pange tähele, et vormid, mille eesmärk on kontaktide kogumine või klienditoega ühenduse võtmine, käivitavad lisaks ka vastava spetsiaalse sündmuse lead.created / contact_form.submitted - tellige neist üks või teine vastavalt sellele, kas soovite üldist või spetsiifilist vaadet, selle asemel et tekitada topelt tegevusi. Nendel kahel sündmuste perekonnal on erinevad sündmuse ID-d; conversationId koos väärtusega timestamp ei ole usaldusväärne esitamise identifikaator.

{
  "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 - vormi püsiv masinnimi, mis ei muutu vormi ümbernimetamisel; kasutage seda esitatud andmete suunamiseks oma süsteemis. formName on külastajatele kuvatav nimi.
  • fields kasutab samu {name, value, type} kirjeid nagu lead.created: mitmikvalikute väärtused on massiivid, failiväärtused on allalaadimislingid.
  • purpose - STANDALONE, LEAD_COLLECTION või HUMAN_CONTACT, olenevalt sellest, kuidas vorm on vestlusrobotiga seotud.

conversation.started

Käivitub, kui külastaja saadab uue vestluse esimese sõnumi.

{
  "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 - külastaja esimese sõnumi täpne tekst. null, kui vestlus avati ilma sõnumi sisuta.
  • chatSource - kanal, mille kaudu vestlus saabus: WIDGET, WHATSAPP, MESSENGER, VOICE, VOICE_PHONE, API, BOOKING, AIRBNB või IDOBOOKING.
  • byAdmin - true, kui vestlus pärineb ChatLabi administraatoripaneelis olevast vestlusroboti eelvaatest, mitte päris külastajalt. Kasutage seda oma testvestluste eraldamiseks CRM-ist.
  • countryCode - külastaja IP-aadressi põhjal määratud ISO-riigikood, null, kui seda ei õnnestunud tuvastada.
  • ipAddress - külastaja IP-aadress ChatLabi vaates, null, kui see pole saadaval. Käsitlege seda GDPR-i järgi isikuandmetena ja salvestage seda ainult seadusliku aluse olemasolul.

conversation.rated

Käivitub, kui külastaja esitab positiivse või negatiivse vestluse hinnangu (vt Vestluse hindamine).

{
  "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 või NEGATIVE. Hinnangu eemaldamine seda sündmust ei käivita, seega ei saa te kunagi neutraalset väärtust.

conversation.summarized

Käivitub, kui ChatLab genereerib lõppenud vestluse kokkuvõtte.

{
  "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_US"
  }
}
  • summary - genereeritud kokkuvõtte tekst. Kokkuvõtte genereerimine toimub asünkroonselt ning sõltub roboti kokkuvõtete seadistusest ja töötlusgraafikust; ärge eeldage fikseeritud edastusaega.
  • language - roboti sisemine lokaat, mis edastati kokkuvõtte tegemiseks, näiteks en_US; ärge eeldage, et see ühtib külastaja vestluskeelega.

client.summarized

Käivitub, kui ChatLab uuendab kliendi tehisintellekti profiili. Profiil koostatakse uuesti eelmise profiili ja äsja lõppenud vestluse kokkuvõtte põhjal ning see võidakse luua pärast sündmust conversation.summarized. Edastusjärjekord ei ole garanteeritud. Päringu keha sisaldab e-posti aadressi, kui see on teada, kuid ChatLab võib hoida ka kliente ilma e-posti aadressita.

{
  "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 - identifikaator kliendi vastendamiseks teie enda CRM-is. Anonüümsete külastajate puhul, kes pole kunagi aadressi jätnud, on selle väärtuseks null, kuid sündmus käivitub ka nende puhul - jätke need edastused vahele, kui teie integratsioon põhineb e-posti aadressil.
  • client - kontaktikirje, mida ChatLab selle isiku kohta hoiab: email, name, phone, countryCode ja ipAddress. Iga võti on alati olemas; tundmatud väärtused on null.
  • clientSummary - täielik profiili tekst tavatekstina, mitte muudatuste loendina (diff). See asendab varasema kokkuvõtte täielikult, seega salvestage see ülekirjutamisena, mitte juurdekirjutamisena.
  • Profiil luuakse uuesti ainult robotite puhul, millel on sisse lülitatud vestlusmälu (chat memory), ja ainult vestluste puhul, mis olid kokkuvõtte tegemiseks piisavalt kaua passiivsed - oodake seda sündmust mõni minut pärast vestluse lõppu, mitte kohe.

live_chat.requested

Käivitub, kui tehisintellekt annab vestluse üle funktsioonile Live Chat, kas seetõttu, et külastaja küsis klienditeenindajat või robot otsustas, et inimese sekkumine on vajalik.

{
  "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 - praegu alati AI, sest üleandmise algatab alati roboti reaalajas vestluse toiming, sealhulgas juhul, kui külastaja seda otsesõnu palub. Käsitlege seda avatud loendina (enum): väärtuse AI eeldamise asemel arvestage ka tundmatute väärtustega.
  • See sündmus hõlmab üleandmist taotlevat tehisintellekti toimingut, mitte iga viisi, kuidas külastaja saab reaalajas vestluse avada. See ei kinnita operaatori liitumist.

live_chat.started

Käivitub, kui reaalajas vestluse seanss luuakse pärast seda, kui külastaja on üleandmisvormi esitanud. See toimub enne seda, kui operaator tingimata liitub või vastab; ärge käsitlege seda inimese sekkumise kinnitusena.

{
  "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 on teadlikult tühi. Kõik vajalik sisaldub ümbrikus: botId tuvastab vestlusroboti ning conversationId / sessionId seovad sündmuse konkreetse vestlusega. Võite selle saada ilma varasema sündmuseta live_chat.requested, näiteks juhul, kui külastaja kasutas vidina reaalajas vestluse juhtelementi.

live_chat.ended

Käivitub, kui reaalajas vestluse seanss lõpeb.

{
  "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 - reaalajas vestluse seansi kestus sekundites alates seansi loomisest, kaasa arvatud operaatori ootamise aeg. Väli jäetakse välja harvadel juhtudel, kui seanss lõpeb ilma, et seda oleks kunagi alustatud.

ai_action.executed

Käivitub iga kord, kui robot käivitab AI toimingu (AI action) - hallatud integratsioonipäringu või kohandatud API funktsiooni. See on suure mahuga sündmus: aktiivne e-kaubanduse robot võib käivitada sadu toiminguid päevas ning külastaja üksainus repliik võib vallandada mitu toimingut. Tellige see eraldi lõpp-punkti või veenduge, et teie vastuvõtja suudab seda mahtu töödelda.

{
  "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 - käivitatud toimingu nimi, nagu tehisintellekt seda näeb, näiteks search_products hallatud integratsiooni puhul või kohandatud API toimingule teie antud nimi.
  • status - SUCCESS või ERROR.
  • durationMs - toimingu kestus millisekundites. Kasulik aeglase integratsiooni tuvastamiseks enne, kui külastajad selle üle kurtma hakkavad.
  • errorMessage - tõrke põhjus, mis on täidetud ainult siis, kui status on ERROR; muul juhul null.

webhook.test

Saadetakse nupuga Send sample event (Saada näidissündmus), kui teete lihtsa ühenduvuskontrolli. Allkirjastatud täpselt nagu päris sündmus.

{
  "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 - fikseeritud tekst, alati sama. Ümbriku väljad kannavad näidisväärtusi, seega ärge kunagi käsitlege sündmuse webhook.test edastust tegelike andmetena.
  • See on ainus sündmuse tüüp, mida te ei saa lõpp-punktis tellida: see saadetakse nõudmisel administraatoripaneelist ja see jõuab alati sellele lõpp-punktile, millel klõpsasite, olenemata sellest, milliseid sündmusi see kuulab.

Turvalisus: edastuste kinnitamine

Iga edastus kannab nelja päist:

Päis Väärtus
X-ChatLab-Signature sha256=<hex hmac> - päringu keha HMAC-SHA256 allkiri
X-ChatLab-Timestamp Unixi aeg sekundites, millal edastus allkirjastati
X-ChatLab-Event Sündmuse tüüp, nt lead.created
X-ChatLab-Delivery Unikaalne edastuse ID, mis võrdub keha väljaga eventId

Allkiri arvutatakse HMAC-SHA256 abil sõne {timestamp}.{rawBody} pealt, kasutades teie lõpp-punkti saladust (secret), kus {timestamp} on X-ChatLab-Timestamp väärtus ja {rawBody} on päringu töötlemata, parsimata keha. Kontrollige alati töötlemata baitide (raw bytes) alusel - pargitud JSON-i uuesti jadastamine muudab baitide järjestust ja muudab allkirja kehtetuks.

Kordusrünnakute (replay attacks) eest kaitsmiseks lükake tagasi edastused, mille X-ChatLab-Timestamp on vanem kui 5 minutit.

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 (typeof signature !== 'string' || typeof timestamp !== 'string') return false;
    if (!/^\d+$/.test(timestamp) || !Number.isSafeInteger(Number(timestamp))) return false;
    if (!Buffer.isBuffer(req.rawBody)) 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 + '.')
        .update(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 === '' || !ctype_digit($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);
}

Kui kinnitamine ebaõnnestub, vastake koodiga 401 ja tühistage sisu. Ärge kunagi töödelge kinnitamata edastusi - igaüks, kes saab teada teie URL-i, võib sinna saata suvalist JSON-i.

Edastuskäitumine

Enne webhookide kasutuselevõttu tutvuge järgmiste edastusreeglitega:

  • Vastake kiiresti. Teie lõpp-punkt peab vastama 3 sekundi jooksul, vastasel juhul loetakse edastus ebaõnnestunuks. Kinnitage allkiri, lisage sündmus kindlalt järjekorda ja kinnitage kättesaamist staatusega 2xx selle ajavahemiku sees. Teostage aeglasemad CRM-i päringud ja äritoimingud asünkroonselt.
  • Tee ja unusta (fire-and-forget), ülimalt üks kord. Sobivad lubatud lõpp-punktid saavad kõige rohkem ühe edastuskatse - uuesti proovimisi ei toimu. Peatatud lõpp-punktid ja avatud ahelad (circuit breaker) võivad takistada isegi seda katset. Kui teie lõpp-punkt ei tööta, tekib ajalõpp või tagastatakse staatus, mis ei ole 2xx, läheb see sündmus kaotsi ja seda ei edastata uuesti. Webhookid on teavitused, mitte kopeeritud andmehoidla: kasutage toetatud juhtudel säilitatud andmete vastavusse viimiseks Bot Talk API vestluste lõpp-punkte või müügivihjete eksporti. Management API hõlmab roboti seadeid ja kasutust, mitte täielikku sündmuste arhiivi. Mõnda sündmust ei saa nende liideste kaudu taastada.
  • Ahelakatkesti (circuit breaker). Pärast 5 järjestikust ebaõnnestunud edastust lõpp-punkti ja roboti paari kohta peatatakse selle paari edastused 5 minutiks. Peatamise ajal toimuvad sündmused jäetakse vahele ning edastuslogis kuvatakse kirjed CIRCUIT_OPEN, mis tähistavad ärajäetud katseid. Avatud ahela tõttu vahelejäänud edastusi ei arvestata automaatse väljalülitamise hulka.
  • Automaatne väljalülitamine. Kontroll toimub edastuse ebaõnnestumise hetkel, mitte kunagi kindla ajavahemiku tagant. Kui edastus ebaõnnestub ja 7 päeva jooksul pole toimunud ühtegi edukat edastust - arvestatuna viimasest õnnestumisest või lõpp-punkti loomise kuupäevast, kui see pole kordagi õnnestunud -, lülitatakse lõpp-punkt välja ja teile saadetakse e-posti teel teavitus. Üksainus 2xx igal ajahetkel lähtestab selle loenduri. Lõpp-punkti, mis ei saa üldse liiklust, ei lülitata kunagi välja, sest midagi ei ebaõnnestu. Kui vastuvõtja on parandatud, lülitage see uuesti sisse menüüst Account settings (konto seaded); tõrgete loendur ja automaatse väljalülitamise märge kustutatakse uuesti sisselülitamisel ning väljalülitatud oleku ajal vahelejäänud sündmusi tagantjärele ei täideta.
  • 410 Gone. Kui teie lõpp-punkt vastab HTTP-staatusega 410 Gone, lülitab ChatLab selle kohe välja. Kasutage seda lõpp-punkti programmilisest kasutusest eemaldamiseks vastuvõtja poolelt.
  • Idempotentsus. Tavapärase toimimise korral dubleerivaid edastusi ei eeldata, kuid kui teie töötlus peab olema rangelt idempotentne, eemaldage duplikaadid väärtuse eventId järgi (saadaval ka päises X-ChatLab-Delivery).

Edastuste järjekord ei ole garanteeritud. Salvestage sündmuse ID ja muutke äritöötlus idempotentseks. Tagage ise webhookide andmesisu (payload) säilitus- ja juurdepääsupoliitikad, kuna need võivad sisaldada isikuandmeid ja failide allalaadimislinke.

Allkirja näidetes kasutatakse teeke Node.js crypto ja PHP funktsiooni hash_equals. Salvestage töötlemata päringu keha (raw request body) enne selle parsimist.

Piirangud

  • Kuni 10 webhooki lõpp-punkti konto kohta.
  • Edastuslogi säilitusaeg: 14 päeva. Vanemad kirjed eemaldatakse automaatselt.

Seotud artiklid

  • Lead collection (müügivihjete kogumine) - vorm sündmuse lead.created taga
  • Human Support Contact form (klienditoe kontaktivorm) - vorm sündmuse contact_form.submitted taga
  • Live Chat - töövoog sündmuste live_chat.* taga
  • Conversation rating (vestluse hindamine) - pöial üles/alla funktsioon sündmuse conversation.rated taga
  • AI Actions - integratsioonid sündmuse ai_action.executed taga
  • Chat API - veebilehitseja vidina tagasikutsed (veebikonksude kliendipoolne vaste)
  • Management API - REST API robotite haldamiseks ja kasutusandmete vaatamiseks
Otsige kõigist artiklitestKüsige agendilt