Вебхук

Что такое нода «Вебхук»

Вебхук — это нода, которая даёт вашему сценарию собственный публичный URL. Любая внешняя система (сайт, CRM, платёжный сервис, другой бот, скрипт) может обратиться на этот адрес обычным HTTP-запросом (GET или POST) — и это запустит выполнение сценария, как если бы пользователь написал боту.

В отличие от ноды-триггера, которая реагирует на события внутри Telegram-ресурса, вебхук реагирует на события снаружи — из любой системы, умеющей делать HTTP-запросы. В отличие от блока «API-запрос», который бот использует, чтобы самому обращаться к внешним сервисам, вебхук — это точка, куда внешние сервисы обращаются к боту.

В каких случаях используется

1. Приём данных извне. Внешняя система присылает вебхуку данные (например, «заказ оплачен», «заявка с сайта», «событие в CRM»), а сценарий сохраняет их в базу данных бота, обновляет переменные пользователя и/или отправляет ему сообщение в Telegram. Так вебхук работает как вход для интеграции с любым сервисом, который умеет отправлять HTTP-запросы, но не имеет собственного модуля для бота.

2. Отдача данных наружу — «бот как API». Внешняя система делает GET-запрос с параметрами, сценарий выполняет блоки (например, «База данных», «API-запрос», «Интеграции»), собирает нужные данные в переменные — а вебхук возвращает их одним JSON-ответом. Так конструктор превращается в простое API поверх ваших сценариев: не нужно поднимать отдельный бэкенд, чтобы отдать наружу то, что уже умеет считать сценарий.

Оба сценария можно совмещать в одной ноде: принять параметры запроса, что-то посчитать/сохранить и одновременно вернуть результат вызывающей стороне.

Как подключить в конструкторе

1. В шапке холста нажмите иконку радиосигнала (перед кнопкой «+» добавления команды) — появится фиолетовая нода «Вебхук».

Кнопка добавления вебхука недоступна внутри подсценариев — вебхук можно разместить только в основном сценарии бота.

2. Откройте ноду — справа откроется панель настроек.
3. Свяжите вебхук с командой: нажмите «Создать», чтобы сразу создать и подключить новую команду, либо выберите существующую в поле «Переход к команде». Именно эта команда будет выполняться при каждом запросе.
4. Добавьте в связанную команду нужные блоки (текст, база данных, API-запрос, установка переменных и т. д.) — они выполнятся при обращении к вебхуку и смогут использовать данные запроса через переменную вебхука (см. ниже).
5. Опубликуйте сценарий — до публикации продакшен-ссылка не работает (см. «Тестовая и продакшен-ссылки» ниже).

Настройки вебхука

Тестовая и продакшен-ссылки

У ноды две ссылки — переключаются вкладками Test URL / Production URL в панели настроек:

Обе ссылки нажатием копируются в буфер обмена. Пока сценарий не опубликован, под вкладкой Production URL показывается подсказка «Опубликуйте сценарий, чтобы активировать продакшен-ссылку».

HTTP-метод и путь

Пользователь по умолчанию

Многие блоки сценария (отправка сообщения, работа с базой данных пользователя и т. д.) требуют ID пользователя. Чтобы не указывать его в каждом блоке отдельно, выберите пользователя по умолчанию — он подставляется автоматически везде, где сценарию нужен ID пользователя.

Если пользователь не выбран, сценарий выполняется «безлично»: переменные считаются и возвращаются в ответе, но сообщения никуда не отправляются — удобно для чистого режима «бот как API».

Если пользователь выбран, сообщения из связанной команды дополнительно отправляются ему на ту платформу, на которой он общается с ботом (Telegram, виджет на сайте, WhatsApp, Instagram, Messenger, email или SMS — в зависимости от того, как он был зарегистрирован).

Авторизация

Логин/пароль и значение заголовка сохраняются отдельной кнопкой «Сохранить» рядом с полями — они хранятся отдельно от схемы сценария и не попадают в экспорт схемы, шаблоны или к ИИ-ассистенту. Запрос без верных учётных данных получает ответ 401 Unauthorized.

Ответ (Respond)

В режиме «После выполнения сценария» вебхук всегда возвращает JSON:

{
  "success": true,
  "variables": { "order_id": "A-114", "api": { "status": "paid" } },
  "messages": [
    { "type": "text", "text": "Заказ A-114 оплачен" }
  ]
}

• variables — все переменные, посчитанные сценарием к моменту завершения команды (включая данные самого запроса).
• messages — контентные блоки команды в том же виде, в котором они уходят пользователю в мессенджер (текст, медиа, кнопки), независимо от того, был ли выбран пользователь по умолчанию для реальной отправки.

В режиме «Сразу» вы настраиваете фиксированный ответ сами — код, тело и заголовки (см. «Расширенные настройки»).

Переменная запроса

Данные входящего запроса сохраняются в переменную, имя которой задаётся полем «Переменная запроса» (по умолчанию webhook). Доступны следующие свойства:

Как и все переменные конструктора, вложенные поля читаются через точку: {{webhook.body.order.id}}, а не {{webhook.body.order[0].id]}} — см. Переменные.

Тестовый запрос и как его сделать

Прежде чем подключать реальную внешнюю систему, удобно проверить, какие данные она присылает, — для этого служит тестовая ссылка.

1. В панели настроек нажмите «Прослушать тестовое событие» — конструктор откроет окно ожидания на 2 минуты.

2. Отправьте запрос на Test URL любым удобным способом:

   Через Postman / Insomnia:

   • Создайте новый запрос, метод — тот, что выбран в настройках ноды (GET или POST).
   • В адресную строку вставьте скопированный Test URL.
   • Для GET — добавьте параметры на вкладке Params; для POST — тело запроса на вкладке Body (JSON или form-data).
   • Нажмите Send.

   Через curl:

   bash

   curl -X POST "https://<ваш-домен>/webhook-test/<slug>/<путь>" \
     -H "Content-Type: application/json" \
     -d '{"order": {"id": 114, "status": "paid"}}'
   

3. Как только запрос дойдёт, в конструкторе появятся его данные — окно ожидания закрывается автоматически.

Тестовая ссылка не выполняет сценарий и не имеет побочных эффектов (ничего не пишет в базу, никому не отправляет сообщений) — она нужна исключительно для того, чтобы увидеть реальную форму присылаемых данных. Последний захваченный запрос сохраняется и остаётся видимым в панели настроек даже после того, как вы переключитесь на другую ноду и вернётесь обратно — до следующего тестового запроса.

Как использовать тестовые данные в сценарии

После захвата тестового запроса под кнопкой прослушивания появляется таблица «Доступные переменные» с конкретными путями к полям присланных данных (например, {{webhook.query.order_id}}, {{webhook.body.customer.email}}) — рядом с каждым показан фактически полученный пример значения.

Эти переменные сразу доступны в автодополнении по всему сценарию: начните вводить {{webhook. в любом текстовом поле блока (текст сообщения, URL API-запроса, условие и т. д.) — появится список с найденными полями. Нажатие на переменную в таблице копирует её в буфер обмена.

Типичный порядок работы:

1. Отправить тестовый запрос с реалистичными данными.
2. Открыть таблицу переменных, скопировать нужные пути.
3. Использовать их в блоках связанной команды: например, в блоке «Установка переменных» сохранить {{webhook.body.order.id}} в переменную order_id, затем текстовым блоком отправить Заказ {{order_id}} принят.
4. Проверить результат ещё одним тестовым запросом при необходимости.
5. Переключиться на Production URL и опубликовать сценарий.

Расширенные настройки

Раскрываются по ссылке «Дополнительные настройки» внизу панели.

IP-адрес запроса и заголовки авторизации проверяются до выполнения сценария — если запрос не прошёл фильтр Ignore Bots, IP Allowlist или авторизацию, привязанная команда не запускается вовсе.

Лог запросов и экспорт

В нижней части панели настроек — свёрнутый блок «Лог запросов» с общим числом записей в заголовке. При раскрытии доступны:

• Фильтры — период (дата от/до), статус (все / успешные / ошибки), поиск по параметрам запроса.
• Компактный список записей: время, статус-код, метод, режим (тест/прод), длительность выполнения, краткая сводка присланных параметров и ответа.
• Пагинация — по 30 записей на страницу.
• Экспорт — кнопка со значком скачивания выгружает все записи, попадающие под текущие фильтры, в JSON-файл с полными данными (заголовки, тело запроса и ответа целиком, без сокращений) — удобно для разбора инцидента или передачи в поддержку.

Записи лога хранятся 7 дней, затем удаляются автоматически ежедневной очисткой. Для истории дольше недели используйте экспорт заранее.