Документация › Интеграции › Вебхуки

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

Обновлено 30 октября 2026 г.

Платформа сама отправляет POST-запрос на ваш адрес, когда в проекте что-то произошло: бот создал заявку, начался новый диалог, прошла оплата, отключился WhatsApp. Так ваша система, Zapier, Make или своя таблица узнают о событии сразу, без опроса.

⏱ 6 мин · 👤 для владельца и разработчика · 🟢 live

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

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

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

События

СобытиеКогда приходит
lead_createdбот оформил заявку
conversation_startedбот ответил в новом диалоге
message_receivedбот ответил в уже существующем диалоге
message_inboundпришло сообщение в WhatsApp: сразу, не дожидаясь ответа бота. Личные чаты и группы, при включённом и выключенном боте, в том числе исходящие с телефона владельца
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: kind (direct или group), direction (in клиент, out вы сами с телефона), conversation_id (пусто у самого первого сообщения нового чата), chat_id, phone, group (адрес, название, автор сообщения и админ ли он), author_name, author_phone, text, message_type (text, image, audio, document, video, sticker, call), media_url (постоянная подписанная ссылка на файл, открывается без ключа), media_mime, provider_message_id, sent_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, таймаут) возможен, как у любого события выше.

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

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

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

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