Вебхуки, события проекта на ваш адрес

Обновлено · 6 минут чтения · для владельца и разработчика

Платформа сама отправляет POST-запрос на ваш адрес, когда в проекте что-то произошло: бот создал заявку, начался новый диалог, прошла оплата, отключился WhatsApp. Так ваша система, Zapier, Make или своя таблица узнают о событии сразу, без опроса.
За 30 секунд:
  • Интеграции → Вебхуки → «Добавить вебхук»: название, адрес https://, события, по желанию заголовки для авторизации.
  • Кнопка «Тест» шлёт пробный запрос и говорит честно: адрес ответил 2xx и вебхук работает, или ответил ошибкой (и какой), или до него не достучаться.
  • Ваш сервер не ответил или ответил 5xx: платформа повторит, до пяти раз.
  • Не путайте с функцией «Своя интеграция по API»: там бот сам идёт к вам посреди разговора, а здесь платформа сообщает о событиях.

Как подключить

  1. Интеграции → Вебхуки → «Добавить вебхук».
  2. Название для себя (например, «CRM вебхук»).
  3. Адрес: только https:// и только публичный адрес (не localhost и не внутренняя сеть).
  4. События: отметьте нужные (список ниже). Они разбиты на две группы: «Уведомления» и «Для своей программы». Во второй стоят «Входящее сообщение (сразу)» (message_inbound), «Сообщение исправлено» (message_edited) и «Сообщение удалено» (message_deleted), у каждого строка, когда оно приходит. Те же события можно включить и через API (events[] при создании или изменении интеграции).
  5. Заголовки запроса (по желанию): JSON для авторизации, например {"Authorization": "Bearer ваш_токен"}. Не нужны, оставьте поле пустым. При редактировании заголовки не показываются: пустое поле сохраняет прежние.
  6. Сохраните и нажмите «Тест»: на адрес придёт запрос с "event": "test", project_id, integration_id, timestamp и message. На экране появится «Адрес ответил 200: вебхук работает» или, если адрес вернул ошибку, её код и что проверить.

События

СобытиеКогда приходит
lead_createdбот оформил заявку
conversation_startedбот ответил в новом диалоге
message_receivedбот ответил в уже существующем диалоге
message_inboundпришло сообщение в WhatsApp, Telegram или Instagram: сразу, не дожидаясь ответа бота, при включённом и выключенном боте. В WhatsApp это личные чаты и группы, в том числе исходящие с телефона владельца; в Telegram и Instagram личные чаты. В форме: группа «Для своей программы»
message_editedсообщение исправили: автор в WhatsApp (личный чат или группа, где включён бот) или в Instagram, либо оператор в кабинете. В форме: группа «Для своей программы»
message_deletedсообщение удалили у всех: автор в WhatsApp (личный чат или группа, где включён бот) или в Instagram, либо оператор в кабинете. В форме: группа «Для своей программы»
payment_receivedклиент оплатил счёт, который выставил бот
ai_errorбот не смог ответить клиенту из-за ошибки ИИ
whatsapp_disconnectedWhatsApp отключился
instagram_disconnectedInstagram отключился (сменили пароль или сняли доступ)
schedule_problemдвижок записи не смог разобрать график
tokens_lowбаланс проекта на исходе
trial_expiringзаканчивается бесплатный период

Что приходит

Тело всегда одной формы:

{
  "event": "lead_created",
  "project_id": "…",
  "timestamp": "2026-10-01T10:15:00.000Z",
  "data": { … }
}

Что лежит в data:

  • lead_created: client_name, phone, lead_status, summary, source_event_name.
  • conversation_started, message_received: chat_id, user_message (что написал клиент), ai_response (что ответил бот), channel.
  • message_inbound: channel (whatsapp, telegram, instagram), kind (direct или group), direction (in клиент, out вы сами с телефона), conversation_id (пусто у самого первого сообщения нового чата), chat_id, phone, group (адрес, название, автор сообщения и админ ли он), author_name, author_phone, author_username (ник в Telegram без «@»), text, message_type (text, image, audio, document, video, sticker, call), media_url (постоянная подписанная ссылка на файл, открывается без ключа), media_mime, provider_message_id, sent_at. У Telegram и Instagram телефона нет (phone и author_phone пустые), а media_url и media_mime в событии пустые: файл в этот момент ещё у мессенджера, берите его из списка сообщений диалога в API (conversation_id). У официального WhatsApp (подключение через Meta) телефон есть, а ссылка на файл в событии тоже пустая. provider_message_id тот же, что придёт в message_edited и message_deleted: по нему события одного сообщения склеиваются.
  • message_edited, message_deleted: channel (whatsapp, instagram, telegram), kind (direct или group), source (messenger: изменил автор в самом мессенджере, у всех в чате так же; cabinet: оператор в кабинете, только в истории DOS AI, у получателя осталось прежнее), conversation_id, chat_id, phone (у личного чата WhatsApp), message_id (тот же id, что в списке сообщений API), provider_message_id, role, direction (in или out), author_name, author_phone, author_is_admin (автор сообщения в группе), message_type, text (у правки новый текст, у удаления удалённый: по нему не действуйте), sent_at, edited_at, deleted_at.
  • Остальные события: event, project_id, project_name, title и body (готовый текст уведомления, тот же, что получает владелец), data (подробности события) и fired_at.

Надёжность

  • Срок ответа 10 секунд. Не уложились, и это считается сбоем.
  • Повторы. Сбой связи, таймаут, ответ 5xx, 408 или 429: событие встаёт в очередь повторов. Очередь разбирается раз в три часа, попыток до пяти, паузы растут, последняя попытка примерно через полтора дня после первой. Ответ 4xx значит «не приму», и такое событие не повторяется: исправьте адрес или авторизацию.
  • Перенаправления не выполняются. Укажите конечный адрес, а не тот, что отвечает 301 или 302.
  • Дубли возможны. Событие вроде «мало баланса» приходит снова, пока причина не устранена, а повтор после сбоя может прийти к уже обработавшему серверу. Считайте приём идемпотентным: ориентируйтесь на event + timestamp и содержимое data.
  • message_inbound приходит один раз на одно новое сообщение. Старая переписка, которую WhatsApp догружает в чат, когда в нём появилось новое сообщение, событием не приходит: она лежит в диалоге и читается запросом сообщений API. Повторная доставка того же сообщения второго события не даёт (ключ provider_message_id, сутки). Сообщение, которое WhatsApp пока не дал расшифровать, придёт своим событием, когда расшифруется. Повтор после вашего сбоя (5xx, таймаут) возможен, как у любого события выше.
  • message_edited и message_deleted приходят один раз на одно изменение. Тот же сигнал от WhatsApp второго события не даёт: удалённое сообщение не удаляется второй раз, правка тем же текстом ничего не меняет. Сообщение удалили раньше, чем оно легло в переписку (секунды после отправки), и событие придёт, как только строка появится, в пределах примерно 40 секунд. В группе события идут только там, где включён бот: сообщений остальных групп у платформы нет.

Журнал доставок. Под списком вебхуков кнопка «Показать» открывает лог последних 30 доставок: событие, адрес, код ответа, время и ошибка.


Авторизация и безопасность

  • Подписи у запросов нет. Проверяйте секрет в заголовке (поле «Заголовки») или в адресе (?secret=…). В журнале доставок адрес хранится без параметров, поэтому секрет из адреса участники проекта не увидят.
  • Служебные заголовки (Host, Content-Length и подобные) задать нельзя, они отбрасываются.
  • Адрес проверяется перед каждой отправкой: внутренние и частные адреса заблокированы, запрос идёт ровно на тот IP, который прошёл проверку.

Дальше: → Своя интеграция по API
Связано: Публичный API · Логи событий · Что можно подключить
Не получилось? → нажмите «Тест» и посмотрите код ответа в журнале доставок