Webhooks

Webhooks pārskats

Webhooks ļauj ChatLab informēt Jūsu sistēmas brīdī, kad kaut kas notiek Jūsu tērzēšanas robotos. Tā vietā, lai periodiski aptaujātu Management API vai eksportētu datus manuāli, Jūs reģistrējat HTTPS galapunktu, un ChatLab reāllaikā nosūta uz to parakstītu HTTP POST pieprasījumu - kad apmeklētājs atstāj pieteikumu (lead), iesniedz saziņas veidlapu, novērtē sarunu, pieprasa sarunu ar cilvēku vai kad tiek izpildīta AI darbība.

Tipiski lietojuma veidi:

• jaunu pieteikumu tūlītēja ievadīšana Jūsu CRM sistēmā to iegūšanas brīdī
• Jūsu komandas informēšana Slack platformā, kad apmeklētājs pieprasa Live Chat (čats reāllaikā)
• sarunu vērtējumu un kopsavilkumu nodošana Jūsu analītikas sistēmās
• AI darbību izpildes uzraudzība un brīdināšana par kļūdām

Pieejamība: Jūsu kontā ir jābūt iekļautai funkcijai Webhooks.

Kur konfigurēt: administratora lietotnē atveriet sadaļu Account settings -> Webhooks (Konta iestatījumi -> Webhooks; tieši blakus sadaļai Management API). Webhooks darbojas konta līmenī - viens galapunkts var saņemt notikumus no visiem Jūsu robotiem vai no viena konkrēta bota.

Galapunkta iestatīšana

1. Atveriet Account settings -> Webhooks un noklikšķiniet uz Add endpoint (Pievienot galapunktu).
2. Aizpildiet galapunkta veidlapu:
   • Name (Nosaukums) - nosaukums Jūsu ērtībai, piemēram, "CRM sinhronizācija" vai "Slack brīdinājumi".
   • URL - HTTPS adrese, uz kuru ChatLab nosūtīs notikumu POST pieprasījumus.
   • Events (Notikumi) - izvēlieties, kādus notikumu veidus šis galapunkts saņems (skatīt katalogu zemāk). Izvēlieties tikai nepieciešamo; liela apjoma notikumi, piemēram, ai_action.executed, var radīt ievērojamu datu plūsmu.
   • Bot filter (Bota filtrs) (neobligāti) - izvēlieties vienu botu vai All bots (Visi roboti), lai saņemtu notikumus no visiem robotiem Jūsu kontā.
   • Custom form filter (Pielāgotās veidlapas filtrs) (neobligāti) - novirza vienas konkrētas pielāgotās veidlapas iesniegumus uz šo galapunktu. Tas sašaurina tikai custom_form.submitted notikumu; visi pārējie abonētie notikumi (pieteikumi, saziņas pieprasījumi, sarunas, čats reāllaikā, AI darbības) tiek piegādāti neatkarīgi no šī iestatījuma.
3. Saglabājiet veidlapu. Galapunkta noslēpums (secret) veiksmīga paziņojuma logā tiek parādīts tikai vienu reizi - nokopējiet to tūlīt un saglabājiet drošā vietā. Tas būs nepieciešams parakstu pārbaudei (skatīt sadaļu Drošība zemāk). Vēlāk vienkārša teksta veidā to vairs nevarēs atgūt.

Katram galapunktam ir pieejami arī šādi iestatījumi:

• Enable/disable toggle (Iespējošanas/atspējošanas slēdzis) - apturiet piegādes, neizdzēšot galapunktu. Atspējoti galapunkti klusējot atmet notikumus (tie netiek ievietoti rindā vēlākai nosūtīšanai).
• Send sample event (Nosūtīt parauga notikumu) - nosūta parakstītu testa pieprasījumu uz Jūsu URL, lai Jūs varētu pārbaudīt uztvērēja darbību no sākuma līdz beigām. Pirms nosūtīšanas varat izvēlēties notikuma veidu un rediģēt parauga vērtības, lai Jūsu apstrādātājs saņemtu reālistiskus datus. Tests tiek saņemts kā parasta piegāde ar eventType, kas atbilst Jūsu izvēlei (vai kā webhook.test vienkāršai savienojamības pārbaudei).
• Roll secret (Ģenerēt jaunu noslēpumu) - ģenerē jaunu noslēpumu un padara nederīgu veco. Izmantojiet to, ja noslēpums varētu būt noplūdis. Jaunais noslēpums atkal tiek parādīts tikai vienu reizi. Kontrolētai nomaiņai apturiet galapunkta darbību, ģenerējiet un nokopējiet jauno noslēpumu, atjauniniet uztvērēju, pēc tam atkārtoti iespējojiet galapunktu un nosūtiet parauga notikumu. Apturēšanas laikā notikumi netiek ievietoti rindā. Ieplānojiet šo pārtraukumu pirms nomaiņas.
• Delivery log (Piegāžu žurnāls) - konkrētā galapunkta pēdējo piegāžu saraksts ar laika zīmogu, notikuma veidu, Jūsu servera atgriezto HTTP statusu un atbildes laiku. Šeit ir redzamas neveiksmīgas piegādes un ķēdes pārtraucēja (circuit breaker) izraisītas pauzes. Žurnāls tiek glabāts 14 dienas.

Notikuma ietvars (envelope)

Katra piegāde ir HTTP POST pieprasījums ar Content-Type: application/json. Paziņojuma pamattekstam vienmēr ir viens un tas pats ietvars; objekts data ir specifisks katram notikuma veidam:

{
  "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āls katram notikumam. Izmantojiet to deduplikācijai, ja apstrādei jābūt idempotents.
• eventType - viens no zemāk aprakstītajiem veidiem; tiek nosūtīts arī galvenē X-ChatLab-Event.
• timestamp - ISO 8601 UTC laiks, kad tika sagatavots piegādes ietvars.
• botId / botName - bots, pie kura pieder notikums.
• conversationId / sessionId - sarunas konteksts, ja piemērojams.

Notikumu katalogs

lead.created

Tiek aktivizēts, kad apmeklētājs iesniedz savu kontaktinformāciju - izmantojot lead collection form (interesentu iegūšanas veidlapu), Live Chat iepriekšējo veidlapu vai pielāgotu veidlapu, kas tiek izmantota interesentu iegūšanai.

{
  "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 - veids, kādā kontaktinformācija tika iegūta: LEAD_COLLECTION_FORM (interesentu iegūšanas veidlapa), LIVE_CHAT_FORM (Live Chat iepriekšējā veidlapa), CONVERSATION (MI datus ieguva sarunas laikā), ADMIN_DATA_UPDATE vai UPDATE_CLIENT_CONTEXT (rediģēts ChatLab pusē). Cilvēku atbalsta veidlapas iesniegšana nekad neaktivizē šo notikumu - tā vietā tiek aktivizēts contact_form.submitted.
• email, name, phone - kontaktinformācija, kas piesaistīta interesenta (lead) ierakstam.
• Ja interesentu iegūšanai tiek izmantota pielāgota veidlapa, visi šajā veidlapā definētie lauki tiek iekļauti fields, veidlapas secībā, un formCodeName / formName identificē veidlapu. Izmantojot klasisko interesentu veidlapu, abi ir null, un fields ir tukšs masīvs.
• Katrs ieraksts fields masīvā ir {name, value, type}. name ir lauka tehniskais nosaukums, kas nemainās pēc nosaukumu rediģēšanas - izmantojiet to kartēšanai savā CRM sistēmā.
• Laukiem multichoice vērtība value ir izvēlēto opciju masīvs. Izvēles rūtiņu lauki ir atsevišķi ieraksti ar vērtībām "true" / "false".
• Laukiem file vērtība value ir augšupielādētā faila lejupielādes saite; tīmekļa pārtvērējs (webhook) nekad nesatur paša faila saturu.
• pageUrl - lapa, kurā apmeklētājs atradās iesniegšanas brīdī.

contact_form.submitted

Tiek aktivizēts, kad apmeklētājs iesniedz cilvēku atbalsta saziņas veidlapu vai pielāgotu veidlapu, ko izmanto saziņai ar cilvēku.

{
  "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 - apmeklētāja norādītā adrese, uz kuru jūsu atbalsta komandai vajadzētu atbildēt.
• source - CUSTOM_FORM, ja pamatā ir pielāgota veidlapa, vai CONTACT_FORM, ja tiek izmantota iebūvētā saziņas veidlapa.
• formCodeName / formName - identificē pielāgoto veidlapu, kas ir pieprasījuma pamatā; iebūvētajai veidlapai abi ir null.
• Ja tiek izmantota pielāgota veidlapa, visi tajā definētie lauki tiek iekļauti fields (tāds pats formāts {name, value, type} kā lead.created). Izmantojot iebūvēto saziņas veidlapu, tiek aizpildīti tikai email un message, fields ir tukšs masīvs, un veidlapas identifikatori ir null.
• message - kartētais ziņojuma lauks vai visas aizpildītās vērtības, kas apvienotas kopā, ja veidlapā nav atsevišķa ziņojuma lauka.

custom_form.submitted

Tiek aktivizēts par katru pielāgotas veidlapas iesniegšanu neatkarīgi no veidlapas mērķa. Ņemiet vērā, ka veidlapas, kuru mērķis ir interesentu iegūšana vai saziņa ar cilvēku, aktivizē arī savu īpašo lead.created / contact_form.submitted notikumu - abonējiet vienu vai otru atkarībā no tā, vai vēlaties vispārīgu vai specializētu skatu, nevis veidojiet dublētas biznesa darbības. Šīm divām notikumu saimēm ir atšķirīgi notikumu ID; conversationId kopā ar timestamp nav uzticams iesniegšanas identifikators.

{
  "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 - nemainīgs sistēmas nosaukums veidlapai, kas nemainās, ja pārdēvējat veidlapu; izmantojiet to, lai maršrutētu iesniegumus savā sistēmā. formName ir apmeklētājiem redzamais nosaukums.
• fields izmanto tādus pašus {name, value, type} ierakstus kā lead.created: vairāku izvēļu vērtības ir masīvi, failu vērtības ir lejupielādes saites.
• purpose - STANDALONE, LEAD_COLLECTION vai HUMAN_CONTACT atkarībā no tā, kā veidlapa ir piesaistīta robotam.

conversation.started

Tiek aktivizēts, kad apmeklētājs nosūta jaunas sarunas pirmo ziņojumu.

{
  "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 - precīzs apmeklētāja ievadziņojuma teksts. null, ja saruna tika atvērta bez ziņojuma satura.
• chatSource - kanāls, kurā tika uzsākta saruna: WIDGET, WHATSAPP, MESSENGER, VOICE, VOICE_PHONE, API, BOOKING, AIRBNB vai IDOBOOKING.
• byAdmin - true, ja saruna notiek robota priekšskatījumā ChatLab administratora panelī, nevis nāk no īsta apmeklētāja. Izmantojiet to, lai jūsu pašu testa sarunas nenonāktu jūsu CRM.
• countryCode - ISO valsts kods, kas noteikts pēc apmeklētāja IP adreses; null, ja to nevarēja noteikt.
• ipAddress - apmeklētāja IP adrese, kādu to redz ChatLab; null, ja tā nav pieejama. Saskaņā ar VDAR uzskatiet to par personas datiem un saglabājiet tikai tad, ja jums tam ir likumīgs pamats.

conversation.rated

Tiek aktivizēts, kad apmeklētājs iesniedz pozitīvu vai negatīvu sarunas vērtējumu (skatiet sadaļu Sarunas novērtēšana).

{
  "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 vai NEGATIVE. Vērtējuma noņemšana neaktivizē šo notikumu, tāpēc neitrālu vērtību jūs nekad nesaņemsiet.

conversation.summarized

Tiek aktivizēts, kad ChatLab ģenerē pabeigtas sarunas kopsavilkumu.

{
  "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 - ģenerētais kopsavilkuma teksts. Kopsavilkuma ģenerēšana notiek asinhroni un ir atkarīga no robota kopsavilkumu konfigurācijas un apstrādes grafika; nepaļaujieties uz fiksētu piegādes laiku.
• language - robota iekšējā lokalizācija, kas nodota kopsavilkuma veidošanai, piemēram, en_US; nepieņemiet, ka tā atbilst apmeklētāja sarunas valodai.

client.summarized

Tiek aktivizēts, kad ChatLab atjaunina klienta MI profilu. Profils tiek izveidots no jauna, izmantojot iepriekšējo profilu un tikko pabeigtās sarunas kopsavilkumu, un tas var tikt ģenerēts pēc conversation.summarized. Piegādes secība netiek garantēta. Datu kopa ietver e-pasta adresi, ja tā ir zināma, taču ChatLab var saglabāt klientus arī bez e-pasta adreses.

{
  "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 - identifikators klienta salīdzināšanai ar jūsu CRM. Anonīmiem apmeklētājiem, kuri nekad nav atstājuši adresi, tas ir null, un šādos gadījumos notikums joprojām tiek aktivizēts - izlaidiet šīs piegādes, ja jūsu integrācija balstās uz e-pasta adresi.
• client - kontaktinformācijas ieraksts, ko ChatLab glabā par šo personu: email, name, phone, countryCode un ipAddress. Katra atslēga ir klātesoša vienmēr; nezināmas vērtības ir null.
• clientSummary - pilns profila teksts vienkārša teksta formātā, nevis izmaiņu saraksts (diff). Tas aizstāj jebkuru iepriekšējo kopsavilkumu, tāpēc saglabājiet to pārrakstot, nevis pievienojot klāt.
• Profils tiek atjaunots tikai tiem robotiem, kuriem ir iespējota sarunu atmiņa, un tikai tām sarunām, kuras bija neaktīvas pietiekami ilgi, lai tiktu apkopotas - sagaidiet šo notikumu dažas minūtes pēc sarunas beigām, nevis uzreiz.

live_chat.requested

Tiek aktivizēts, kad MI nodod sarunu Live Chat (tiešsaistes tērzēšanai), vai nu tāpēc, ka apmeklētājs lūdza operatoru, vai tāpēc, ka robots nolēma, ka ir nepieciešams cilvēks.

{
  "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 - pašlaik vienmēr AI, jo nodošanu vienmēr iniciē robota Live Chat darbība, tostarp gadījumos, kad apmeklētājs to pieprasa parastos vārdos. Uztveriet to kā atvērtu skaitījumu (enum): apstrādājiet nezināmas vērtības, nevis paļaujieties tikai uz AI.
• Šis notikums attiecas uz MI darbību, kas pieprasa nodošanu, nevis uz jebkuru veidu, kā apmeklētājs var atvērt tiešsaistes tērzēšanu. Tas nepierāda, ka operators ir pievienojies.

live_chat.started

Tiek aktivizēts, kad pēc apmeklētāja nodošanas veidlapas iesniegšanas tiek izveidota tiešsaistes tērzēšanas sesija. Tas notiek pirms operators obligāti ir pievienojies vai atbildējis; neuztveriet to kā pierādījumu cilvēka iesaistei.

{
  "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 apzināti ir tukšs. Viss nepieciešamais ir ietvarā: botId identificē robotu, un conversationId / sessionId piesaista notikumu sarunai. Jūs varat to saņemt bez iepriekšēja live_chat.requested, piemēram, ja apmeklētājs izmantoja logrīka (widget) Live Chat vadīklu.

live_chat.ended

Tiek aktivizēts, kad beidzas tiešsaistes tērzēšanas sesija.

{
  "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 - pagājušais tiešsaistes tērzēšanas sesijas ilgums sekundēs, skaitot no sesijas izveides, ieskaitot operatora gaidīšanas laiku. Lauks tiek izlaists retos gadījumos, kad sesija beidzas, pat netikusi faktiski sākta.

ai_action.executed

Tiek aktivizēts katru reizi, kad robots izpilda MI darbību - pārvaldītu integrācijas izsaukumu vai pielāgotu API funkciju. Šis ir liela apjoma notikums: aktīvs e-komercijas robots var izpildīt simtiem darbību dienā, un viena apmeklētāja ziņa var aktivizēt vairākas darbības. Abonējiet to uz atsevišķu galapunktu vai pārliecinieties, ka jūsu uztvērējs spēj apstrādāt šādu apjomu.

{
  "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 - izpildītās darbības nosaukums, kādu to redz MI, piemēram, search_products pārvaldītai integrācijai vai nosaukums, ko piešķīrāt pielāgotai API darbībai.
• status - SUCCESS vai ERROR.
• durationMs - darbības izpildes ilgums milisekundēs. Noderīgi, lai pamanītu lēnu integrāciju, pirms apmeklētāji par to sūdzas.
• errorMessage - kļūdas iemesls, kas aizpildīts tikai tad, ja status ir ERROR; pretējā gadījumā null.

webhook.test

Tiek nosūtīts, nospiežot pogu Send sample event (Nosūtīt parauga notikumu), kad veicat vienkāršu savienojamības pārbaudi. Parakstīts tieši tāpat kā īsts notikums.

{
  "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 - fiksēts teksts, vienmēr viens un tas pats. Ietvara laukos ir parauga vērtības, tāpēc nekad neuztveriet webhook.test sūtījumu kā reālus datus.
• Šis ir vienīgais notikumu veids, kuru nevar abonēt galapunktā: tas tiek nosūtīts pēc pieprasījuma no administratora paneļa un vienmēr sasniedz galapunktu, uz kura noklikšķinājāt, neatkarīgi no tā, kādus notikumus tas klausās.

Drošība: sūtījumu pārbaude

Katrs sūtījums ietver četras galvenes:

Galvene	Vērtība
X-ChatLab-Signature	sha256=<hex hmac> - datu kravas HMAC-SHA256 paraksts
X-ChatLab-Timestamp	Unix laiks sekundēs, kad sūtījums tika parakstīts
X-ChatLab-Event	Notikuma veids, piemēram, lead.created
X-ChatLab-Delivery	Unikāls piegādes ID, kas atbilst pamatteksta eventId

Paraksts tiek aprēķināts kā HMAC-SHA256 virknei {timestamp}.{rawBody}, izmantojot jūsu galapunkta noslēpumu (secret), kur {timestamp} ir X-ChatLab-Timestamp vērtība un {rawBody} ir neapstrādāts, neparsēts pieprasījuma pamatteksts. Vienmēr pārbaudiet parakstu pret neapstrādātiem baitiem - atkārtota parsētā JSON serializēšana mainīs baitu secību un sabojās parakstu.

Lai aizsargātos pret atkārtošanas uzbrukumiem (replay attacks), noraidiet sūtījumus, kuru X-ChatLab-Timestamp ir vecāks par 5 minūtēm.

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

Ja pārbaude neizdodas, atbildiet ar statusa kodu 401 un noraidiet pieprasījuma saturu. Nekad neapstrādājiet nepārbaudītus sūtījumus - ikviens, kurš uzzina jūsu URL, var nosūtīt tam brīvi izvēlētu JSON saturu ar POST pieprasījumu.

Piegādes darbība

Pirms sākat izmantot webhook, ņemiet vērā šos piegādes noteikumus:

• Atbildiet ātri. Jūsu galapunktam ir jāatbild 3 sekunžu laikā, pretējā gadījumā piegāde tiek uzskatīta par neveiksmīgu. Šajā laika posmā pārbaudiet parakstu, droši ievietojiet notikumu rindā un apstipriniet saņemšanu ar 2xx statusa kodu. Lēnākus CRM izsaukumus un biznesa loģikas apstrādi veiciet asinhroni.
• Nosūtīt un aizmirst (fire-and-forget), ne vairāk kā vienu reizi (at-most-once). Atbilstošie iespējotie galapunkti saņem ne vairāk kā vienu piegādes mēģinājumu - atkārtotu mēģinājumu nav. Pauzēti galapunkti un atvērtas ķēdes (open circuits) var apturēt pat šo vienīgo mēģinājumu. Ja jūsu galapunkts nedarbojas, iestājas taimauts vai tas atgriež statusa kodu, kas nav 2xx, šis notikums ir zaudēts un netiks piegādāts atkārtoti. Webhook ir paziņojumi, nevis replicēta datu krātuve: izmantojiet Bot Talk API sarunu galapunktus vai lead datu eksportēšanu, lai saskaņotu saglabātos datus, kur tas ir atbalstīts. Management API ietver bota iestatījumus un lietojumu, nevis pilnīgu notikumu arhīvu. Dažus notikumus, izmantojot šīs saskarnes, nav iespējams atjaunot.
• Automātiskais slēdzis (circuit breaker). Pēc 5 secīgām neveiksmīgām piegādēm konkrētajam galapunkta/bota pārim piegādes šim pārim tiek apturētas uz 5 minūtēm. Notikumi, kas rodas šīs pauzes laikā, tiek atmesti, un piegādes žurnālā parādās CIRCUIT_OPEN ieraksti, kas palīdz identificēt apturētos mēģinājumus. Piegādes, kas izlaistas atvērtas ķēdes dēļ, netiek ieskaitītas automātiskās atspējošanas skaitītājā.
• Automātiskā atspējošana. Pārbaude tiek veikta brīdī, kad piegāde neizdodas, nevis pēc taimera. Ja piegāde neizdodas un 7 dienas nav bijis nevienas veiksmīgas piegādes - skaitot no pēdējās veiksmīgās piegādes vai no galapunkta izveides datuma, ja tas nekad nav darbojies veiksmīgi -, galapunkts tiek izslēgts un jūs saņemat e-pasta paziņojumu. Viens veiksmīgs 2xx statusa kods jebkurā brīdī atiestata šo laika skaitīšanu. Galapunkts, kas nesaņem datplūsmu, nekad netiek atspējots, jo nekas necieš neveiksmi. Iespējojiet to no jauna sadaļā Account settings (Konta iestatījumi), tiklīdz jūsu uztvērēja darbība ir novērsta; kļūmju skaitītājs un automātiskās atspējošanas atzīme tiek notīrīta, kad to atkal ieslēdzat, un notikumi, kas palaisti garām izslēgtā stāvokļa laikā, netiek atkārtoti ielādēti.
• 410 Gone. Ja jūsu galapunkts atbild ar HTTP 410 Gone, ChatLab to nekavējoties atspējo. Izmantojiet to, lai programmatiski pārtrauktu galapunkta darbību uztvērēja pusē.
• Idempotence. Standarta darbības režīmā piegāžu dublēšanās netiek gaidīta, taču, ja jūsu apstrādei jābūt stingri idempotentai, novērsiet dublikātus, izmantojot eventId (pieejams arī galvenē X-ChatLab-Delivery).

Piegādes secība netiek garantēta. Saglabājiet notikuma ID un padariet biznesa loģikas apstrādi出力 idempotentu. Pārvaldiet savus datu saglabāšanas un piekļuves kontroles noteikumus attiecībā uz webhook saturu, jo tajā var būt ietverti personas dati un failu lejupielādes saites.

Paraksta piemēros tiek izmantots Node.js crypto un PHP funkcija hash_equals. Iegūstiet neapstrādāto pieprasījuma pamattekstu (raw request body) pirms tā parsēšanas.

Ierobežojumi

• Līdz 10 webhook galapunktiem vienā kontā.
• Piegādes žurnāla glabāšana: 14 dienas. Vecāki ieraksti tiek dzēsti automātiski.

Saistītie raksti

• Lead collection - veidlapa, kas nodrošina lead.created
• Human Support Contact form - veidlapa, kas nodrošina contact_form.submitted
• Live Chat - plūsma, kas nodrošina live_chat.* notikumus
• Conversation rating - vērtējums ar īkšķi uz augšu/leju, kas nodrošina conversation.rated
• AI Actions - integrācijas, kas nodrošina ai_action.executed
• Chat API - pārlūkprogrammas logrīka atzvanīšanas funkcijas (klienta puses alternatīva webhook)
• Management API - REST API botu pārvaldībai un lietojuma datiem