Вебхуки

Вебхуки приложения

На странице «Вебхуки» developer-приложение настраивает отправку выбранных событий на внешний URL. Один webhook может слушать несколько типов событий, а у одного приложения может быть несколько webhooks с разными адресами и наборами событий.

Для рабочего endpoint используйте HTTPS. Публичное событие приложения ожидает ответ до 60 секунд на попытку, но обработчику лучше быстро принять событие в собственную очередь и вернуть 2xx.

Вкладка «Общие» содержит публичные события приложения, «Для инструментов» — запросы HTTP-инструментов, а «Для шагов» — внутренние webhook шагов автоматизаций. У всех видов есть история запросов, однако режим ожидания результата агента применяется только к инструментам.

Какие события доступны

• command_start — пользователь отправил /start; в data приходят command и args;
• message_allow — пользователь разрешил отправку сообщений;
• message_new — новое сообщение пользователя; текст находится в data.content;
• button_clicked — пользователь нажал кнопку в сообщении;
• lead_created — создан лид;
• lead_unsubscribed — пользователь отписался от сообщений;
• lead_blocked — пользователь заблокировал бота;
• segment_subscribed — лид подписан на сегмент;
• segment_unsubscribed — лид отписан от сегмента;
• message_undelivered — «Не удалось отправить сообщение»: ошибка отправки сообщения агента, автоматизации или оператора;
• error — «Ошибка выполнения агента»: не удалось обработать запрос к агенту, например из-за таймаута ИИ или недостаточного баланса;
• automation_step_failed — «Ошибка шага автоматизации»: шаг окончательно завершился ошибкой, автоматические повторы исчерпаны или для этой ошибки не предусмотрены.

Общие поля JSON, содержимое data, обязательность значений и условия возникновения каждого типа описаны в справочнике формата событий. Для подписок и отписок используйте раздел о сегментах.

Вебхук приложения получает выбранные события сегментов из всех проектов с активной установкой приложения. Используйте project_id и data.segment_id, чтобы определить проект и сегмент события.

Как создать вебхук

На странице вебхуков откройте вкладку «Общие», затем:

1. Нажмите «Добавить».
2. В форме создания задайте понятное название webhook, например «Новые сообщения в CRM».
3. Укажите полный URL обработчика.
4. Галочками отметьте один или несколько типов событий. Сначала показывается понятное описание события, под ним — технический псевдоним для payload.
5. Нажмите «Создать».

Новый webhook сразу получает статус «Активен».

Тест и повторные попытки

У нужного webhook в списке откройте меню действий и выберите «Тест».

Откроется окно проверки с методом, URL, заголовками и JSON-телом будущего запроса. До нажатия «Запустить» запрос не отправляется. После запуска в том же окне отображаются результат, HTTP-статус, время, тело ответа и причина ошибки, если она возникла.

Тест выполняет один запрос с собственным event_id, event_type: "test", project_id: "test", пустыми идентификаторами и сообщением в data. Заголовки и подпись формируются по тем же правилам, что и для боевого события. Обработчик должен принимать этот служебный тип отдельно от списка боевых событий.

Тест считается успешным только при HTTP-ответе 200-299 и показывает код и время ответа. Это один немедленный запрос без повторов; он может ждать ответ до 60 секунд.

Боевое событие ставится в очередь с окном повторов в один день. При сетевой ошибке, тайм-ауте, HTTP 408, 425, 429 или ответе 5xx выполняется до 12 попыток: сразу, затем примерно через 1, 5, 15 и 30 минут, 1, 2, 4, 8, 12, 18 и 24 часа. Другой ответ 4xx, в том числе 401 или 403, завершает операцию без автоматических повторов: сначала нужно разобраться с причиной отказа. После исправления доступа запрос с ответом 401 или 403 можно повторить вручную. Во всех автоматических попытках сохраняются тот же event_id и данные события. В Standard Webhooks обновляются webhook-timestamp и подпись; тело сохраняется. В Senler Webhook Standard обновляются также timestamp тела и X-Webhook-Timestamp. Выбор описан в форматах подписи. Поэтому повтор нужно распознавать по event_id и отвечать 2xx, если событие уже надёжно принято.

Вебхуки инструментов

Вкладка «Для инструментов» показывает HTTP-инструменты приложения и созданные для них webhook. URL, параметры и режим выполнения задаются в конструкторе инструмента; со страницы webhook можно перейти к редактированию инструмента.

Вкладка «Для шагов» показывает внутренние webhook шагов автоматизаций. Адрес и контракт задаются в конструкторе шага; со страницы webhook можно открыть историю его вызовов или вернуться к редактированию шага.

Вызовы HTTP-инструментов подписываются единым секретом вебхуков приложения из блока выше. Отдельного секрета у каждого инструмента нет.

• в мгновенном режиме агент ждёт один ответ, а автоматических повторов нет;
• в режиме ожидания результата запрос ставится в очередь, и агент продолжает шаг после успешной доставки;
• в фоновом режиме запрос тоже ставится в очередь, но ответ не продолжает текущий шаг агента.

Тело вызова содержит event_type: "tool_call", идентификаторы события, приложения, установки, проекта, агента и диалога, необязательный lead_id, системное имя и tool_instance_id, а также arguments, обычную configuration и закрытые private_data экземпляра. Заголовки и подпись строятся по правилам раздела «Секрет и подпись» с единым секретом приложения. Обработчик должен проверять подпись и входные данные, не записывать приватные данные в открытые логи и возвращать результат, понятный агенту. Режимы, тайм-ауты, окна повторов и точный пример тела описаны в разделе «Инструменты агента».

Подробные инструкции

• Формат событий: Общие поля JSON, данные каждого события, примеры и значения источников подписки на сегмент.
• События ошибок: Подпишитесь на ошибки агентов и отправки сообщений. Это содержимое событий, а не ошибки HTTP-доставки вебхука.
• Доставка вебхуков: Проверяйте доставку событий приложению, находите причину ошибок и повторяйте неудачные запросы.
• Подпись вебхуков: Проверяйте подпись входящих запросов с помощью секрета вебхука и обновляйте секрет при необходимости.