Palīdzības centrs
Chat API

Webhooks

Pēdējo reizi atjaunināts:

Webhook pārskats

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

Tipiski lietošanas veidi:

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

Pieejamība: webhook ir pieejami, sākot no STANDARD plāna (funkcija: Webhooks).

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

Galapunkta iestatīšana

  1. Atveriet Account settings -> Webhooks un noklikšķiniet uz Create endpoint (Izveidot 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) - atlasiet, kādu veidu notikumus šis galapunkts saņems (skatiet 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 (Robotu filtrs) (neobligāts) - ierobežojiet galapunktu konkrētiem robotiem. Atstājiet tukšu, lai saņemtu notikumus no visiem robotiem Jūsu kontā.
    • Custom form filter (Pielāgoto veidlapu filtrs) (neobligāts) - novirza vienas pielāgotās veidlapas iesniegumus uz šo galapunktu. Tas sašaurina tikai notikumu custom_form.submitted; 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. Iesniedziet veidlapu. Galapunkta slepenā atslēga (secret) tiek parādīta tieši vienu reizi apstiprinājuma logā - nokopējiet to tūlīt un glabājiet drošā vietā. Tā būs nepieciešama, lai verificētu parakstus (skatiet sadaļu Drošība zemāk). Vēlāk vienkārša teksta veidā to vairs nevarēs atgūt.

Katram galapunktam ir arī:

  • Iespējošanas/atspējošanas slēdzis (Enable/disable toggle) - apturiet piegādes, nedzēšot galapunktu. Atspējotie galapunkti automātiski ignorē 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 savu uztvērēju pilnā ciklā. 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 slepeno atslēgu) - izveido jaunu slepeno atslēgu un anulē veco. Izmantojiet to, ja atslēga varētu būt noplūdusi. Jaunā slepenā atslēga atkal tiek parādīta tikai vienu reizi. Pirms atslēgas maiņas atjauniniet savu uztvērēju, pretējā gadījumā piegādēm Jūsu pusē neizdosies verificēt parakstu.
  • Delivery log (Piegādes žurnāls) - konkrētā galapunkta neseno 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 pārtraucēja (circuit breaker) pauzes. Žurnāls tiek glabāts 14 dienas.

Notikuma ietvars (envelope)

Katra piegāde ir HTTP POST pieprasījums ar Content-Type: application/json. Pamattekstam vienmēr ir viens un tas pats ietvars; objekts data ir atkarīgs no konkrētā notikuma veida:

{
  "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 dublikātu novēršanai, ja Jūsu apstrādei jābūt idempotentu.
  • eventType - viens no tālāk dokumentētajiem veidiem; tiek nosūtīts arī galvenē X-ChatLab-Event.
  • timestamp - ISO 8601 UTC laiks, kad notikums noticis.
  • botId / botName - robots, 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 pieteikumu vākšanas veidlapu, čata reāllaikā ievades veidlapu vai pieteikumu vākšanai izmantoto pielāgoto veidlapu.

{
  "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 (pieteikumu vākšanas veidlapa), LIVE_CHAT_FORM (čata reāllaikā ievades veidlapa), CONVERSATION (AI ieguva datus sarunas laikā), ADMIN_DATA_UPDATE vai UPDATE_CLIENT_CONTEXT (rediģēts ChatLab pusē). Klientu atbalsta veidlapas iesniegumi nekad neaktivizē šo notikumu - to vietā tiek aktivizēts contact_form.submitted.
  • email, name, phone - kontaktinformācija, kas piesaistīta pieteikuma ierakstam.
  • Ja pieteikumu vākšanai tiek izmantota pielāgota veidlapa, katrs tajā definētais lauks tiek iekļauts masīvā fields veidlapas secībā, un formCodeName / formName identificē šo veidlapu. Klasiskajai pieteikumu veidlapai abi ir null, un fields ir tukšs masīvs.
  • Katrs ieraksts masīvā fields ir formātā {name, value, type}. name ir lauka tehniskais nosaukums, kas nemainās pēc etiķešu rediģēšanas - izmantojiet to sasaistei ar Jūsu CRM.
  • Laukos 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".
  • Laukos file vērtība value ir augšupielādētā faila lejupielādes saite; webhook nekad nesatur 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 klientu atbalsta saziņas veidlapu vai pielāgotu veidlapu, kas paredzēta saziņai ar operatoru.

{
  "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 jāatbild.
  • source - CUSTOM_FORM, ja saziņas veidlapas pamatā ir pielāgota veidlapa, vai CONTACT_FORM, ja tiek izmantota iebūvētā veidlapa.
  • formCodeName / formName - identificē pieprasījuma pamatā esošo pielāgoto veidlapu; iebūvētajai veidlapai abi ir null.
  • Izmantojot pielāgotu veidlapu, visi tajā definētie lauki tiek iekļauti masīvā fields (tāds pats {name, value, type} formāts kā notikumam lead.created). Iebūvētajai saziņas veidlapai tiek aizpildīti tikai email un message, fields ir tukšs masīvs un veidlapas identifikatori ir null.
  • message - piesaistī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 katras pielāgotās veidlapas iesniegšanas gadījumā neatkarīgi no veidlapas mērķa. Ņemiet vērā: ja veidlapas mērķis ir pieteikumu vākšana vai saziņa ar atbalstu, tā papildus aktivizē arī atbilstošo notikumu lead.created / contact_form.submitted - abonējiet vienu vai otru atkarībā no tā, vai Jums nepieciešams vispārīgs vai specializēts skats, un novērsiet dublikātus pēc conversationId + timestamp, ja abonējat abus.

{
  "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"},
      {"photo", "value": "https://api.chatlab.com/aichat/customform/download?key=...&token=...", "type": "file"}
    ],
    "purpose": "STANDALONE"
  }
}
  • formCodeName - stabils sistēmas veidlapas nosaukums, kas nemainās, pārdēvējot veidlapu; izmantojiet to, lai maršrutētu iesniegumus savā sistēmā. formName ir apmeklētājiem redzamais nosaukums.
  • Masīvā fields tiek izmantoti tie paši {name, value, type} ieraksti kā notikumam 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 saistīta ar tērzēšanas robotu.

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 pirmā ziņojuma teksts. null, ja saruna tika atvērta bez ziņojuma satura.
  • chatSource - kanāls, caur kuru saņemta saruna: WIDGET, WHATSAPP, MESSENGER, VOICE, VOICE_PHONE, API, BOOKING, AIRBNB vai IDOBOOKING.
  • byAdmin - true, ja saruna nāk no tērzēšanas robota priekšskatījuma ChatLab administratora panelī, nevis no reāla apmeklētāja. Izmantojiet to, lai Jūsu pašu testa sarunas nenonāktu CRM sistēmā.
  • countryCode - ISO valsts kods, kas noteikts pēc apmeklētāja IP adreses; null, ja to neizdevās noteikt.
  • ipAddress - apmeklētāja IP adrese, kādu to redz ChatLab; null, ja tā nav pieejama. Uzskatiet to par personas datiem saskaņā ar VDAR (GDPR) un glabājiet to tikai tad, ja Jums ir likumīgs pamats.

conversation.rated

Tiek aktivizēts, kad apmeklētājs novērtē robota atbildi ar īkšķi uz augšu vai uz leju (skatiet sadaļu Sarunu vē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 notikumu neaktivizē, 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"
  }
}
  • summary - izveidotais kopsavilkuma teksts. Kopsavilkumi tiek izveidoti dažas minūtes pēc tam, kad saruna kļūst neaktīva, tāpēc šis notikums tiek saņemts vēlāk nekā pārējie sarunas notikumi.
  • language - tās valodas ISO kods, kādā tika sagatavots kopsavilkums (atbilst sarunas valodai).

client.summarized

Tiek aktivizēts, kad ChatLab atjaunina klienta AI profilu. Profils tiek izveidots no jauna, apvienojot iepriekšējo profilu ar tikko pabeigtās sarunas kopsavilkumu, tāpēc šis notikums seko notikumam conversation.summarized par to pašu sarunu. Klienti tiek identificēti pēc e-pasta, tāpēc adrese tiek atkārtota objekta data augstākajā līmenī.

{
  "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 saskaņošanai ar Jūsu CRM. Anonīmiem apmeklētājiem, kuri nav atstājuši e-pasta adresi, tā vērtība ir null, bet notikums viņiem tik un tā tiek aktivizēts - izlaidiet šīs piegādes, ja Jūsu integrācija balstās uz e-pastu.
  • client - kontaktinformācijas ieraksts, ko ChatLab glabā par šo personu: email, name, phone, countryCode un ipAddress. Katra atslēga vienmēr ir klāt; nezināmas vērtības ir null.
  • clientSummary - pilns profila teksts vienkāršā tekstā, nevis kā izmaiņu saraksts (diff). Tas aizstāj iepriekšējo kopsavilkumu, tāpēc saglabājiet to pārrakstot, nevis pievienojot klāt.
  • Profils tiek izveidots no jauna tikai robotiem ar iespējotu sarunu atmiņu un tikai sarunām, kas bija neaktīvas pietiekami ilgi, lai tiktu izveidots kopsavilkums - rēķinieties, ka šis notikums ieradīsies dažas minūtes pēc sarunas beigām, nevis uzreiz.

live_chat.requested

Tiek aktivizēts, kad AI nodod sarunu uz Live Chat, jo apmeklētājs lūdza operatoru vai robots izlē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 ir AI, jo nodošanu vienmēr iniciē robota čata reāllaikā darbība, tostarp gadījumos, kad apmeklētājs to pieprasa parastiem vārdiem. Uzskatiet to par atvērtu enum: apstrādājiet nezināmas vērtības, nevis paļaujieties tikai uz AI.
  • Šis notikums norāda, ka nodošana ir pieprasīta, nevis to, ka operators to ir pieņēmis. Lai uzzinātu par pieņemšanu, sagaidiet live_chat.started.

live_chat.started

Tiek aktivizēts, kad operators pievienojas un faktiski sākas čata reāllaikā sesija.

{
  "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": {}
}
  • Objekts data apzināti ir tukšs. Viss nepieciešamais ir ietvarā: botId identificē tērzēšanas robotu, bet conversationId / sessionId piesaista notikumu sarunai, par kuru jau esat saņēmis notikumu live_chat.requested.

live_chat.ended

Tiek aktivizēts, kad čata reāllaikā sesija beidzas.

{
  "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 - laiks sekundēs, cik ilgi operators piedalījās sarunā, skaitot no sesijas sākuma brīža. Lauks tiek izlaists retos gadījumos, kad sesija beidzas, pat netikusi uzsākta.

ai_action.executed

Tiek aktivizēts katru reizi, kad robots izpilda AI darbību - pārvaldītu integrācijas izsaukumu vai pielāgotu API funkciju. Šis ir liela apjoma notikums: aktīvs e-komercijas robots dienā var izpildīt simtiem darbību, un viena apmeklētāja kārta var aktivizēt vairākas. Abonējiet to atsevišķam galapunktam 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 AI, piemēram, search_products pārvaldītai integrācijai vai nosaukums, ko piešķīrāt pielāgotajai API darbībai.
  • status - SUCCESS vai ERROR.
  • durationMs - darbības izpildes ilgums milisekundēs. Noderīgi, lai pamanītu lēnu integrāciju, pirms par to sāk sūdzēties apmeklētāji.
  • errorMessage - kļūmes iemesls; tiek aizpildīts tikai tad, ja status ir ERROR; pretējā gadījumā ir null.

webhook.test

Nosūta poga 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 iekļautas parauga vērtības, tāpēc nekad neuztveriet webhook.test piegādi kā reālus datus.
  • Šis ir vienīgais notikuma veids, ko galapunktā nevar abonēt: tas tiek nosūtīts pēc pieprasījuma no administratora paneļa un vienmēr nonāk tajā galapunktā, uz kura noklikšķinājāt, neatkarīgi no tā, kādus notikumus tas klausās.

Drošība: piegāžu verificēšana

Katra piegāde ietver četras galvenes:

Galvene Vērtība
X-ChatLab-Signature sha256=<hex hmac> - datu ziņojuma (payload) HMAC-SHA256 paraksts
X-ChatLab-Timestamp Unix laiks sekundēs, kad piegāde tika parakstīta
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 veiciet verifikāciju, izmantojot neapstrādātos baitus - atkārtota parsēta JSON serializācija mainīs baitu secību un sabojās parakstu.

Lai aizsargātos pret atkārtošanas uzbrukumiem (replay attacks), noraidiet piegādes, 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 (!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);
}

Ja verifikācija neizdodas, atbildiet ar kodu 401 un noraidiet datu ziņojumu. Nekad neapstrādājiet neverificētas piegādes - ikviens, kurš uzzina Jūsu URL, var nosūtīt tam patvaļīgu JSON, izmantojot POST pieprasījumu.

Piegādes darbības principi

Pirms veidojat risinājumus, izmantojot webhook, iepazīstieties ar šiem nosacījumiem:

  • Atbildiet ātri. Jūsu galapunktam ir jāatbild 3 sekunžu laikā, pretējā gadījumā piegāde tiek uzskatīta par neizdevušos. Nekavējoties atbildiet ar 2xx kodu un apstrādājiet datu ziņojumu asinhroni (ievietojiet to rindā un pēc tam apstipriniet saņemšanu) - neveiciet CRM izsaukumus vai ierakstus datubāzē pirms atbildes nosūtīšanas.
  • Nosūtīt un aizmirst, ne vairāk kā vienu reizi (fire-and-forget, at-most-once). Katram notikumam ir tieši viens piegādes mēģinājums - atkārtoti mēģinājumi netiek veikti. Ja Jūsu galapunkts nedarbojas, iestājas noildze vai tas atgriež statusu, 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: ja nepieciešama garantēta datu pilnība, veiciet salīdzināšanu ar Management API vai Jūsu lead eksporta datiem.
  • Ķēdes pārtraucējs (circuit breaker). Pēc 5 secīgām neveiksmīgām piegādēm vienam botam šī bota piegādes tiek apturētas uz 5 minūtēm. Notikumi, kas rodas pauzes laikā, tiek atmesti, un piegādes žurnālā parādās CIRCUIT_OPEN ieraksti, lai Jūs varētu precīzi redzēt, kad un kāpēc datu plūsma tika apturēta. Piegādes, kas izlaistas atvērta ķēdes pārtraucēja dēļ, netiek ieskaitītas automātiskās atspējošanas skaitītājā.
  • Automātiska atspējošana. Pārbaude tiek veikta brīdī, kad piegāde neizdodas, un tā nekad netiek darbināta 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 statuss jebkurā brīdī atiestata šo laika skaitīšanu. Galapunkts, kas nesaņem datu plūsmu, nekad netiek atspējots, jo nekas necieš neveiksmi. Atkārtoti iespējojiet to sadaļā Account settings (Konta iestatījumi), tiklīdz uztvērējs ir salabots; kļūmju skaitītājs un automātiskās atspējošanas atzīme tiek dzēsti, kad to atkal ieslēdzat, un notikumi, kas palaisti garām izslēgšanas laikā, netiek atkārtoti aizpildīti.
  • 410 Gone. Ja Jūsu galapunkts atbild ar HTTP statusu 410 Gone, ChatLab to nekavējoties atspējo. Izmantojiet to, lai programmatiski pārtrauktu galapunkta darbību no saņēmēja puses.
  • Idempotence. Standarta darbības apstākļos dublētas piegādes nav gaidāmas, taču, ja Jūsu apstrādes procesam ir jābūt stingri idempotentam, veiciet deduplikāciju pēc eventId (pieejams arī galvenē X-ChatLab-Delivery).

Ierobežojumi

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

Saistītie raksti

  • Lead collection (Pieteikumu ievākšana) - veidlapa, kas nodrošina lead.created
  • Human Support Contact form (Klientu atbalsta saziņas veidlapa) - veidlapa, kas nodrošina contact_form.submitted
  • Live Chat - darbplūsma, kas nodrošina live_chat.* notikumus
  • Conversation rating (Sarunas vērtējums) - īkšķis 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 webhookiem)
  • Management API - REST API botu pārvaldībai un lietojuma datiem
Meklēt visus rakstusJautājiet aģentam