Вебхуки, события проекта на ваш адрес
Обновлено · 6 минут чтения · для владельца и разработчика
Платформа сама отправляет POST-запрос на ваш адрес, когда в проекте что-то произошло: бот создал заявку, начался новый диалог, прошла оплата, отключился WhatsApp. Так ваша система, Zapier, Make или своя таблица узнают о событии сразу, без опроса.
За 30 секунд:
- Интеграции → Вебхуки → «Добавить вебхук»: название, адрес
https://, события, по желанию заголовки для авторизации.- Кнопка «Тест» шлёт пробный запрос и говорит честно: адрес ответил 2xx и вебхук работает, или ответил ошибкой (и какой), или до него не достучаться.
- Ваш сервер не ответил или ответил 5xx: платформа повторит, до пяти раз.
- Не путайте с функцией «Своя интеграция по API»: там бот сам идёт к вам посреди разговора, а здесь платформа сообщает о событиях.
Как подключить
- Интеграции → Вебхуки → «Добавить вебхук».
- Название для себя (например, «CRM вебхук»).
- Адрес: только
https://и только публичный адрес (неlocalhostи не внутренняя сеть). - События: отметьте нужные (список ниже). Они разбиты на две группы: «Уведомления» и «Для своей программы». Во второй стоят «Входящее сообщение (сразу)» (
message_inbound), «Сообщение исправлено» (message_edited) и «Сообщение удалено» (message_deleted), у каждого строка, когда оно приходит. Те же события можно включить и через API (events[]при создании или изменении интеграции). - Заголовки запроса (по желанию): JSON для авторизации, например
{"Authorization": "Bearer ваш_токен"}. Не нужны, оставьте поле пустым. При редактировании заголовки не показываются: пустое поле сохраняет прежние. - Сохраните и нажмите «Тест»: на адрес придёт запрос с
"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_disconnected | WhatsApp отключился |
instagram_disconnected | Instagram отключился (сменили пароль или сняли доступ) |
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 · Логи событий · Что можно подключить
Не получилось? → нажмите «Тест» и посмотрите код ответа в журнале доставок