Центр допомоги
Chat API

Webhooks

Останнє оновлення:

Огляд Webhooks

Webhooks дозволяють ChatLab сповіщати ваші системи в той самий момент, коли щось відбувається у ваших чатботах. Замість опитування Management API або ручного експорту даних ви реєструєте HTTPS-ендпоінт, і ChatLab надсилає на нього підписаний HTTP POST у реальному часі - коли відвідувач залишає лід, надсилає контактну форму, оцінює розмову, запитує людину або коли виконується дія AI.

Типові сценарії використання:

  • передавання нових лідів безпосередньо у вашу CRM щойно вони зафіксовані
  • сповіщення вашої команди в Slack, коли відвідувач запитує чат наживо
  • передавання оцінок розмов і підсумків у власну аналітику
  • моніторинг виконання дій AI та сповіщення про помилки

Доступність: ваш обліковий запис повинен містити функцію Webhooks.

Де налаштувати: у панелі керування відкрийте Account settings -> Webhooks (Налаштування облікового запису -> Webhooks, поруч із розділом Management API). Webhooks діють на рівні облікового запису - один ендпоінт може отримувати події від усіх ваших ботів або від одного вибраного бота.

Налаштування ендпоінта

  1. Відкрийте Account settings -> Webhooks і натисніть Add endpoint (Додати ендпоінт).
  2. Заповніть форму ендпоінта:
    • Name (Назва) - мітка для вашої зручності, наприклад, "Синхронізація з CRM" або "Сповіщення в Slack".
    • URL - HTTPS-адреса, на яку ChatLab надсилатиме події через POST.
    • Events (Події) - виберіть, які типи подій отримує цей ендпоінт (дивіться каталог нижче). Вибирайте лише те, що вам потрібно; високонавантажені події на кшталт ai_action.executed можуть створювати великий обсяг трафіку.
    • Bot filter (Фільтр ботів) (необов'язково) - виберіть одного бота або All bots (Усі боти) для всіх ботів у вашому обліковому записі.
    • Custom form filter (Фільтр спеціальних форм) (необов'язково) - спрямовує надсилання однієї конкретної спеціальної форми на цей ендпоінт. Це обмежує лише подію custom_form.submitted; усі інші події, на які ви підписалися (ліди, контактні запити, розмови, чат наживо, дії AI), доставляються незалежно від цього налаштування.
  3. Надішліть форму. Secret (секретний ключ) ендпоінта відображається лише один раз у вікні успішного створення - скопіюйте його зараз і збережіть у безпечному місці. Він знадобиться вам для перевірки підписів (дивіться розділ "Безпека" нижче). Відкритий текст пізніше отримати неможливо.

Кожен ендпоінт також має:

  • Перемикач увімкнення/вимкнення (Enable/disable toggle) - призупиняйте доставку без видалення ендпоінта. Вимкнені ендпоінти безслідно відхиляють події (вони не стають у чергу на потім).
  • Send sample event (Надіслати тестову подію) - доставляє підписаний тестовий запит на вашу URL-адресу, щоб ви могли перевірити свій приймач від початку до кінця. Ви можете вибрати тип події та відредагувати тестові значення перед відправленням, щоб ваш обробник бачив реалістичні дані. Тест надходить як звичайна доставка з eventType, що відповідає вашому вибору (або як webhook.test для простої перевірки з'єднання).
  • Roll secret (Оновити секретний ключ) - генерує новий секретний ключ і анулює старий. Використовуйте це, якщо секретний ключ міг бути скомпрометований. Новий секретний ключ також показується лише один раз. Для контрольованої ротації призупиніть ендпоінт, згенеруйте та скопіюйте новий ключ, оновіть приймач, потім знову ввімкніть і надішліть тестову подію. Події під час паузи не стають у чергу. Заплануйте цю перерву перед ротацією.
  • Delivery log (Журнал доставок) - список останніх доставок для кожного ендпоінта з міткою часу, типом події, HTTP-статусом, повернутим вашим сервером, і часом відповіді. Тут відображаються невдалі доставки та зупинки за допомогою circuit breaker. Журнал зберігається протягом 14 днів.

Оболонка події

Кожна доставка - це HTTP POST із Content-Type: application/json. Тіло завжди має однакову оболонку; об'єкт data залежить від типу події:

{
  "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 - унікальний ідентифікатор події. Використовуйте його для дедуплікації, якщо ваша обробка має бути ідемпотентною.
  • eventType - один із типів, описаних нижче; також надсилається в заголовку X-ChatLab-Event.
  • timestamp - час за ISO 8601 UTC, коли була підготовлена оболонка доставки.
  • botId / botName - бот, якому належить подія.
  • conversationId / sessionId - контекст розмови, коли це застосовно.

Каталог подій

lead.created

Спрацьовує, коли відвідувач надсилає свої контактні дані - через форму збору лідів, попередню форму Live Chat або кастомну форму, призначену для збору лідів.

{
  "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 - спосіб отримання контактних даних: LEAD_COLLECTION_FORM (форма збору лідів), LIVE_CHAT_FORM (попередня форма Live Chat), CONVERSATION (ШІ отримав дані під час діалогу), ADMIN_DATA_UPDATE або UPDATE_CLIENT_CONTEXT (відредаговано на стороні ChatLab). Відправлення форми звернення до людини ніколи не викликають цієї події - замість неї спрацьовує contact_form.submitted.
  • email, name, phone - контактні дані, занесені до запису ліда.
  • Якщо для збору лідів використовується кастомна форма, кожне поле, визначене в ній, додається до fields у порядку розташування у формі, а formCodeName / formName ідентифікують саму форму. Для класичної форми лідів обидва значення дорівнюють null, а fields є порожнім масивом.
  • Кожен запис у fields має формат {name, value, type}. name - це технічна назва поля, що не змінюється під час редагування підписів; використовуйте її для зіставлення з вашою CRM.
  • Для полів типу multichoice значення value є масивом обраних варіантів. Поля з прапорцями (checkbox) передаються окремими записами зі значеннями "true" / "false".
  • Для полів типу file значення value є посиланням на завантаження переданого файлу; вебхук ніколи не містить самого вмісту файлу.
  • pageUrl - сторінка, на якій перебував відвідувач у момент надсилання.

contact_form.submitted

Спрацьовує, коли відвідувач надсилає контактну форму звернення до людини або кастомну форму, призначену для зв'язку з людиною.

{
  "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 - адреса, яку залишив відвідувач, і на яку ваша служба підтримки має надіслати відповідь.
  • source - CUSTOM_FORM, якщо в основі контактної форми лежить кастомна форма, або CONTACT_FORM для стандартної вбудованої форми.
  • formCodeName / formName - ідентифікують кастомну форму, яка стоїть за цим запитом; для стандартної форми обидва параметри дорівнюють null.
  • Якщо використовується кастомна форма, кожне поле, визначене в ній, додається до fields (той самий формат {name, value, type}, що й у lead.created). Для стандартної контактної форми заповнюються лише email та message, fields залишається порожнім масивом, а ідентифікатори форми дорівнюють null.
  • message - зіставлене поле повідомлення або всі заповнені значення, об'єднані разом, якщо у формі немає окремого поля повідомлення.

custom_form.submitted

Спрацьовує під час кожного надсилання кастомної форми, незалежно від її призначення. Зверніть увагу: форми, призначенням яких є збір лідів або звернення до людини, також надсилають свої спеціалізовані події lead.created / contact_form.submitted. Підписуйтеся на ту чи іншу подію залежно від того, чи потрібен вам загальний, чи спеціалізований вигляд, щоб уникнути дублювання бізнес-дій. Ці дві групи подій мають різні ідентифікатори подій; пара conversationId та timestamp не є надійним ідентифікатором відправлення.

{
  "eventId": "6c1d8e3f-2a5b-4c7d-9e0f-1a4b6c8d0e2f",
  "eventType": "custom_form.submitted",
  "timestamp": "2026-08-13T14:27:45Z",
  "botId": 1234,
  "botName": "Support Bot",
  "conversationId": "conv_a1b2c3",
  "sessionId": "sess_x9y8z7",
  "data": {
    "formCodeName": "warranty_claim",
    "formName": "Warranty claim",
    "fields": [
      {"name": "order_number", "value": "A-10293", "type": "text"},
      {"name": "issue", "value": "Damaged on arrival", "type": "textarea"},
      {"name": "photo", "value": "https://api.chatlab.com/aichat/customform/download?key=...&token=...", "type": "file"}
    ],
    "purpose": "STANDALONE"
  }
}
  • formCodeName - постійна технічна назва форми, яка не змінюється під час перейменування; використовуйте її для маршрутизації відповідей у вашій системі. formName - це назва, яка відображається відвідувачам.
  • fields містить такі самі елементи {name, value, type}, як і lead.created: значення множинного вибору є масивами, а значення файлів - посиланнями на завантаження.
  • purpose - STANDALONE, LEAD_COLLECTION або HUMAN_CONTACT, залежно від того, як форма підключена до чатбота.

conversation.started

Спрацьовує, коли відвідувач надсилає перше повідомлення в новій розмові.

{
  "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 - точний текст першого повідомлення відвідувача. null, якщо розмову було розпочато без тексту повідомлення.
  • chatSource - канал, через який надійшла розмова: WIDGET, WHATSAPP, MESSENGER, VOICE, VOICE_PHONE, API, BOOKING, AIRBNB або IDOBOOKING.
  • byAdmin - значення true, якщо діалог ведеться через вікно попереднього перегляду чатбота в панелі адміністратора ChatLab, а не справжнім відвідувачем. Використовуйте цей параметр, щоб ваші тестові чати не потрапляли до CRM.
  • countryCode - код країни за стандартом ISO, визначений за IP-адресою відвідувача, або null, якщо його не вдалося визначити.
  • ipAddress - IP-адреса відвідувача, зафіксована ChatLab, або null, якщо вона недоступна. Згідно з GDPR ця інформація є персональними даними - зберігайте її лише за наявності законних підстав.

conversation.rated

Спрацьовує, коли відвідувач ставить позитивну чи негативну оцінку розмові (див. Оцінювання розмов).

{
  "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 або NEGATIVE. Скасування оцінки не викликає цієї події, тому ви ніколи не отримаєте нейтрального значення.

conversation.summarized

Спрацьовує, коли ChatLab генерує підсумок завершеної розмови.

{
  "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 - згенерований текст підсумку. Створення підсумку відбувається асинхронно та залежить від налаштувань підсумків бота й розкладу черги обробки; не розраховуйте на фіксований час надходження.
  • language - внутрішня локаль бота, передана для створення підсумку, наприклад en_US; не вважайте, що вона обов'язково збігається з мовою діалогу відвідувача.

client.summarized

Спрацьовує, коли ChatLab оновлює ШІ-профіль клієнта. Профіль формується на основі попереднього профілю та підсумку розмови, яка щойно завершилася, і може генеруватися після події conversation.summarized. Черговість надходження не гарантується. Корисне навантаження містить електронну пошту, якщо вона відома, проте ChatLab також може вести записи про клієнтів без адреси електронної пошти.

{
  "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 - ідентифікатор для пошуку відповідного клієнта у вашій CRM. Він дорівнює null для анонімних відвідувачів, які не залишили контактів; подія для них усе одно викликається, тому пропускайте такі сповіщення, якщо ваша інтеграція спирається на email.
  • client - контактні дані цієї людини, наявні в ChatLab: email, name, phone, countryCode та ipAddress. Усі ключі завжди присутні; невідомі значення позначаються як null.
  • clientSummary - повний текст профілю у форматі звичайного тексту, а не дифу (змін). Він повністю замінює попередній підсумок, тому зберігайте його способом перезапису, а не додавання до попереднього.
  • Профіль оновлюється лише для ботів із увімкненою пам'яттю чату і лише для розмов, які були неактивними достатньо довго для формування підсумку - очікуйте на цю подію через кілька хвилин після завершення розмови, а не миттєво.

live_chat.requested

Спрацьовує, коли ШІ передає розмову до Live Chat (чату наживо) через те, що відвідувач попросив покликати людину, або тому, що бот вирішив, що потрібне втручання оператора.

{
  "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 - наразі завжди має значення AI, оскільки передача завжди ініціюється відповідною дією бота для чату наживо, навіть коли про це прямо попросив відвідувач. Сприймайте це поле як відкрите перерахування (open enum): передбачте обробку невідомих значень, замість жорсткої перевірки на рівність AI.
  • Ця подія охоплює виклик дії передачі оператору з боку ШІ, а не всі можливі способи, якими відвідувач може відкрити чат наживо. Вона не гарантує того, що оператор дійсно приєднався.

live_chat.started

Спрацьовує, коли після заповнення форми передачі створюється сесія чату наживо. Це відбувається до того, як оператор обов'язково підключиться чи надішле відповідь; не сприймайте цю подію як факт підключення людини.

{
  "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 навмисно залишено порожнім. Усе необхідне є в заголовках конверта: botId ідентифікує чатбота, а conversationId / sessionId зв'язують подію з конкретною розмовою. Ви можете отримати цю подію без попереднього надходження live_chat.requested, наприклад якщо відвідувач скористався кнопкою переходу до оператора у віджеті.

live_chat.ended

Спрацьовує після завершення сесії чату наживо.

{
  "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 - тривалість сесії Live Chat у секундах, яка вимірюється з моменту її створення і включає час очікування оператора. Поле пропускається в рідкісних випадках, коли сесія завершується, так і не розпочавшись фактично.

ai_action.executed

Спрацьовує щоразу, коли бот виконує дію ШІ (AI action) - виклик керованої інтеграції або кастомну API-функцію. Ця подія генерує великий обсяг трафіку: активний e-commerce бот може виконувати сотні дій на день, а одна репліка відвідувача здатна запустити відразу кілька дій. Підписуйтеся на неї на окремому ендпоінті або переконайтеся, що ваш сервер здатен витримати таке навантаження.

{
  "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 - назва виконаної дії так, як її бачить ШІ, наприклад search_products для керованої інтеграції або назва, яку ви призначили кастомній API-дії.
  • status - SUCCESS або ERROR.
  • durationMs - час виконання дії в мілісекундах. Зручно для виявлення повільних інтеграцій ще до того, як відвідувачі почнуть скаржитися.
  • errorMessage - причина помилки, заповнюється лише тоді, коли status дорівнює ERROR; в інших випадках має значення null.

webhook.test

Надсилається після натискання кнопки Send sample event (Надіслати тестову подію) під час базової перевірки з'єднання. Підписується точно так само, як і реальна подія.

{
  "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 - фіксований текст, який не змінюється. Поля конверта містять зразкові тестові значення, тому ніколи не обробляйте повідомлення webhook.test як справжні дані.
  • Це єдиний тип події, на який не можна підписатися в налаштуваннях ендпоінта: вона відправляється за запитом із панелі адміністратора й завжди надходить на той ендпоінт, де ви натиснули кнопку тесту, незалежно від налаштованих фільтрів подій.

Безпека: перевірка автентичності сповіщень

Кожне надіслане повідомлення містить чотири HTTP-заголовки:

Header Value
X-ChatLab-Signature sha256=<hex hmac> - підпис корисного навантаження за алгоритмом HMAC-SHA256
X-ChatLab-Timestamp Час у форматі Unix (у секундах), коли було підписано сповіщення
X-ChatLab-Event Тип події, наприклад lead.created
X-ChatLab-Delivery Унікальний ідентифікатор доставки, що збігається з eventId у тілі запиту

Підпис обчислюється як HMAC-SHA256 від рядка {timestamp}.{rawBody} з використанням секретного ключа вашого ендпоінта, де {timestamp} - це значення заголовка X-ChatLab-Timestamp, а {rawBody} - сире, нерозібране тіло запиту. Завжди виконуйте перевірку на основі необроблених байтів: повторна серіалізація розібраного JSON змінить послідовність символів і призведе до невідповідності підпису.

Щоб захиститися від атак повторного відтворення (replay attacks), відхиляйте запити, у яких заголовок X-ChatLab-Timestamp старіший за 5 хвилин.

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

Якщо перевірка підпису не вдалася, поверніть відповідь зі статусом 401 і відкиньте отримані дані. Ніколи не обробляйте неперевірені сповіщення - будь-хто, хто дізнається вашу URL-адресу, може надіслати на неї довільний JSON-запит.

Поведінка доставки

Ознайомтеся з цими правилами доставки перед початком роботи з webhook:

  • Відповідайте швидко. Ваша кінцева точка повинна відповісти протягом 3 секунд, інакше спроба доставки вважатиметься невдалою. Перевірте підпис, надійно додайте подію до черги та підтвердьте отримання статусом 2xx у межах цього часового вікна. Виконуйте повільніші виклики до CRM і бізнес-обробку асинхронно.
  • Fire-and-forget, щонайбільше один раз. Відповідні увімкнені кінцеві точки отримують щонайбільше одну спробу доставки - повторних спроб немає. Призупинені кінцеві точки та розімкнені запобіжники можуть заблокувати навіть цю спробу. Якщо ваша кінцева точка недоступна, час очікування вичерпано або вона повертає статус, відмінний від 2xx, ця подія втрачається і не буде надіслана повторно. Webhook - це сповіщення, а не репліковане сховище даних: використовуйте кінцеві точки розмов Bot Talk API або експорт лідів для звірки збережених даних, де це підтримується. Management API охоплює налаштування бота та використання, а не повний архів подій. Деякі події неможливо відновити через ці інтерфейси.
  • Автоматичний вимикач (Circuit breaker). Після 5 поспіль невдалих доставок для пари кінцева точка/бот доставки для цієї пари призупиняються на 5 хвилин. Події, що відбуваються під час паузи, відкидаються, а журнал доставок відображає записи CIRCUIT_OPEN для позначення заблокованих спроб. Доставки, пропущені через розімкнений запобіжник, не враховуються для автоматичного вимкнення.
  • Автоматичне вимкнення. Перевірка запускається в момент невдалої доставки, а не за розкладом. Якщо спроба доставки зазнає невдачі і протягом 7 днів не було жодної успішної доставки - відлік ведеться від останнього успіху або від дати створення кінцевої точки, якщо вона ніколи не мала успішних доставок - кінцева точка вимикається, і ви отримуєте сповіщення електронною поштою. Один-єдиний статус 2xx у будь-який момент скидає цей відлік. Кінцева точка, яка не отримує трафіку, ніколи не вимикається, оскільки немає невдалих спроб. Увімкніть її знову в Account settings (Налаштування облікового запису), коли приймач буде виправлено; лічильник помилок і мітка автоматичного вимкнення скидаються під час повторного ввімкнення, а події, пропущені під час її неактивності, не відновлюються.
  • 410 Gone. Якщо ваша кінцева точка відповідає статусом HTTP 410 Gone, ChatLab негайно вимикає її. Використовуйте це для програмного виведення кінцевої точки з експлуатації з боку отримувача.
  • Ідемпотентність. Повторні доставки не очікуються за нормальної роботи, але якщо ваша обробка повинна бути суворо ідемпотентною, виконуйте дедуплікацію за полем eventId (воно також доступне в заголовку X-ChatLab-Delivery).

Порядок доставки не гарантується. Зберігайте ID події та забезпечуйте ідемпотентність бізнес-обробки. Забезпечте власні політики зберігання даних і контроль доступу для корисного навантаження webhook, яке може містити персональні дані та посилання для завантаження файлів.

Приклади перевірки підпису використовують Node.js crypto та функцію hash_equals у PHP. Отримуйте сире тіло запиту перед його синтаксичним аналізом.

Ліміти

  • До 10 кінцевих точок webhook на обліковий запис.
  • Термін зберігання журналу доставок: 14 днів. Старіші записи видаляються автоматично.

Пов'язані статті

  • Збір лідів - форма, що стоїть за подією lead.created
  • Форма зв'язку зі службою підтримки - форма, що стоїть за подією contact_form.submitted
  • Live Chat - сценарій, що стоїть за подіями live_chat.*
  • Оцінка розмови - оцінки «палець вгору/вниз», що стоять за подією conversation.rated
  • AI Actions - інтеграції, що стоять за подією ai_action.executed
  • Chat API - зворотні виклики віджета у браузері (клієнтський аналог webhook)
  • Management API - REST API для керування ботами та перегляду даних про використання
Шукати серед усіх статейЗапитати агента