Главная · Справка · Входящий и исходящий webhook

Входящий и исходящий webhook

В сценарии ЧБТ два вебхука, и они направлены в разные стороны. «Входящий webhook» — триггер: ваша система отправляет POST на адрес ЧБТ, и сценарий стартует. «HTTP-запрос» — действие: сценарий отправляет POST с данными контакта на ваш адрес. Третий механизм живёт вне сценария — подписка бота на события диалогов в разделе «Интеграции и API», о ней в конце. Ниже — адреса, формат тел, секреты и главное ограничение входящего вебхука, о котором спрашивают чаще всего.

Действие «HTTP-запрос»: из бота — наружу

Ставится в блоке «Действие» в любом месте сценария. Настройки: URL вашей стороны, метод (по умолчанию POST) и, по желанию, имя переменной, в которую записать ответ.

Тело запроса — JSON с заголовком Content-Type: application/json:

{
  "contact": { "id": 1234, "tags": "[\"запись\",\"стрижка\"]" },
  "vars": { "phone": "+79990000000", "name": "Анна", "slot": "завтра к 15" },
  "text": "завтра к 15",
  "channelType": "telegram"
}

contact — идентификатор контакта в ЧБТ и его теги; теги приходят строкой в формате JSON-массива, распарсьте её на своей стороне.
vars — переменные сценария. Сюда попадает то, что «Сбор данных» сохранил через поле «В переменную», и то, что записано действием «Записать переменную». Если телефон и имя нужны в запросе — включите «В переменную» в соответствующих блоках сбора.
text — последнее сообщение клиента.
channelType — telegram, max, vk или web.

Ответ сервера (тело как текст) можно сохранить «В переменную» и показать клиенту следующим «Сообщением» через {{имя}} — так делается «статус заказа из вашей учётной системы». Ожидание ответа — до 15 секунд; при ошибке или таймауте сценарий продолжается, ошибка пишется в лог ЧБТ, повторных попыток нет. Подписи запроса нет — проверяйте источник по секретному сегменту в URL (https://ваш-сервер/hook/длинная-случайная-строка).

Пример: заявка в Make или n8n

В Make создайте сценарий с модулем «Custom webhook», в n8n — узел «Webhook». Скопируйте выданный адрес.
В ЧБТ после блоков «Сбор данных» (Имя и Телефон, оба «В переменную») поставьте «Действие» → «HTTP-запрос» с этим адресом.
Напишите боту как клиент в подключённом Telegram или виджете. В тест-чате «Проверить сценарий» HTTP-запрос не отправляется, поэтому структуру полей Make/n8n покажут по первому настоящему запросу.
Дальше в том же сценарии Make/n8n — модуль amoCRM, Битрикс24, Google Sheets или письмо: поля vars.name, vars.phone, contact.tags раскладываются по нужным местам.

Готовые подключения в ЧБТ есть только к Битрикс24 и Омнидеску, для остальных CRM это и есть стандартная связка. Разбор с вариантами «встроенная CRM или своя» — в статье лиды из бота в CRM; обзор всех точек обмена — на странице интеграций.

Триггер «Входящий webhook»: извне — в сценарий

Добавьте в сценарий триггер «Входящий webhook» и задайте «Путь webhook» — короткое слово латиницей, например order-paid. Кабинет покажет готовый адрес:

POST https://app.chbt.io/webhook/inbound/<ID бота>/order-paid?token=<секрет>

Секрет генерируется кнопкой «Сгенерировать» в настройках триггера и передаётся либо в ?token=, либо в заголовке X-Webhook-Token. Запросы без верного токена получают 401. У старых триггеров без секрета проверки нет — включите её кнопкой и обновите URL в своей системе.

Тело запроса — JSON, все поля необязательны:

{ "uid": "order-1042", "text": "paid", "name": "Заказ 1042" }

uid — идентификатор события или объекта; одинаковый uid в повторных запросах продолжит тот же служебный диалог, разные — создадут разные.
text — попадёт в сценарий как текст сообщения (по умолчанию event).
name — имя служебного контакта в «Диалогах» (по умолчанию «Webhook»).

Сценарий должен быть включён (✓ в колонке «Активен»), а в боте — подключён канал «Виджет на сайт»: входящий webhook работает через него. Ответ ЧБТ — {"ok":true}; 404 no_trigger означает, что путь не совпал или сценарий выключен.

Что входящий webhook делает — и чего не делает

Делает: запускает сценарий как отдельное событие. Полезные продолжения — «Действие» → «Сделка в CRM» («Оплата: {{name}}»), «Уведомить оператора» (Web Push и сообщение в кабинете), «Добавить тег» служебному контакту, «HTTP-запрос» дальше по цепочке.

Не делает: не находит существующего клиента в Telegram, MAX или ВКонтакте и не отправляет ему сообщение. Событие приходит для служебного контакта в канале виджета, а не для Иванова, который вчера писал вашему боту, — ЧБТ не связывает uid из запроса с его Telegram-аккаунтом. Поэтому схема «учётная система узнала о статусе → клиент получил сообщение в мессенджере» через входящий webhook не собирается; так же он не поставит тег реальному клиенту и не запустит для него «Паузу».

Как в ЧБТ делаются адресные уведомления:

по запросу клиента — кнопка «Где мой заказ» → «Сбор данных» номера → «HTTP-запрос» к вашей системе (ответ «В переменную») → «Сообщение» со статусом; статус заказа с Ozon и Wildberries ЧБТ по номеру не получает — такой вопрос уходит оператору;
рассылкой по тегу — для событий, которые касаются группы («заказы этой недели отправлены»); тег ставит сценарий или администратор в «Контактах»;
оператором из «Диалогов» — шаблон быстрого ответа в уже существующем диалоге.

Почему так устроено и как жить с правилом «сначала пишет клиент» — в статье уведомления клиентам через бота. Оба вебхука доступны на Бесплатном тарифе.

Вебхуки на события диалогов: подписка бота

Подписка настраивается не в сценарии, а в разделе «Интеграции и API» бота: адрес, набор событий и секрет подписи. События — шесть: message.inbound (сообщение покупателя), message.outbound (ответ бота или оператора; если это карточки товаров — с названием, ценой, валютой, ссылкой, фото и наличием), conversation.started, conversation.handoff (передан человеку), conversation.closed и contact.created. Событий о заказах, оплатах и показах товара нет.

Тело — JSON с полями event, id, occurredAt, project, а по смыслу события — conversation, contact и message. В заголовках — X-Chbt-Event, X-Chbt-Delivery, X-Chbt-Timestamp и X-Chbt-Signature: HMAC-SHA256 в hex от строки «метка времени, точка, сырое тело». Сверяйте подпись сравнением постоянного времени и отбрасывайте запросы, чья метка отличается от текущего времени больше чем на 5 минут. Если адрес не ответил, ЧБТ делает до пяти попыток с паузой от 30 секунд до часа; редиректы не выполняются, адреса внутренней сети не принимаются. Журнал доставок с кодом ответа вашего сервера виден в том же разделе.

Для Битрикс24 и Омнидеска тело собираем мы в их формате — лид или обращение, поэтому подписи там нет. Ответить покупателю из внешней системы помогает публичный API.

Частые вопросы

Может ли входящий webhook отправить сообщение конкретному клиенту в Telegram?
Нет. Он запускает сценарий как отдельное событие для служебного контакта и не связан с диалогами реальных клиентов. Адресные уведомления делаются по запросу клиента в сценарии, рассылкой по тегу или из «Диалогов».

Какие поля приходят в HTTP-запросе?
JSON: contact (id и теги), vars (переменные сценария), text (последнее сообщение клиента), channelType (канал). Телефон и имя попадают в vars, если в «Сборе данных» включено «В переменную».

Есть ли повторные попытки, если мой сервер не ответил?
Нет. ЧБТ ждёт до 15 секунд, при ошибке продолжает сценарий и пишет ошибку в лог. Принимайте вебхуки сервисом с очередью (Make, n8n) или отвечайте 200 сразу и обрабатывайте позже.

Можно ли не указывать секрет входящего webhook?
Технически старые триггеры без секрета принимаются, но любой, кто узнает адрес, сможет запускать сценарий. Нажмите «Сгенерировать» и передавайте токен в ?token= или заголовке X-Webhook-Token.

Создать бота бесплатно

Интеграции Лиды из бота в CRM Переменные API ЧБТ