Документация

Вебхуки

Документация

Вебхуки — способ, которым платформа уведомляет ваши системы о происходящем: звонок начался, сессия завершилась, цель достигнута. Вы подписываетесь, указав URL; при срабатывании события платформа отправляет POST с JSON-телом на этот URL.

Эта страница описывает события, контракт доставки и схему подписи. Подписки управляются во вкладке Webhooks вашего проекта.

Каталог событий

Сегодня доступно пять событий:

  • session.started — срабатывает, когда звонок соединён и агент начинает говорить. Несёт идентификатор сессии, идентификатор сценария, направление (входящий/исходящий), маскированный номер телефона звонящего (например +3412•••789 — полный номер доступен через GET /v1/sessions/{id}) и признак тестовой сессии.
  • session.ended — срабатывает по окончании звонка. Несёт идентификатор сессии, финальный статус (completed / abandoned / failed), длительность и признак достижения цели. Полную запись сессии — транскрипт, слоты, исход — получайте через GET /v1/sessions/{id}.
  • session.failed — срабатывает, когда сессия завершилась ошибкой. Несёт идентификатор сессии и причину сбоя.
  • goal.achieved — срабатывает в момент, когда агент достигает цели сценария, прямо посреди звонка, один раз за сессию. В теле — определение цели и значения слотов, собранные к этому моменту. Используйте его для побочных эффектов, которые нужны сразу, а не по окончании сессии.
  • intent.classified — срабатывает, когда классификатор интентов выбирает сценарий в проекте с несколькими сценариями. Полезно для аудита и измерения точности маршрутизации.

Сегодня вебхуки покрывают голосовые сессии; события для разговоров в мессенджерах и завершения пакетов — в планах.

Подписка

Во вкладке Webhooks проекта создайте подписку:

  • URL — куда вы принимаете POST-запросы. Только HTTPS.
  • События — выберите из каталога. Одно событие, несколько или все.

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

На проект допускается до 10 подписок.

Формат тела запроса

Каждое тело — JSON с общим конвертом:

{
  "event": "session.ended",
  "deliveryId": "5b2c4f8a-…",
  "ts": "2026-05-13T18:42:11Z",
  "tenantId": "…",
  "projectId": "…",
  "data": { … }
}

Схема объекта data своя у каждого события. Доставка выполняется по принципу «как минимум один раз», и deliveryId не меняется между повторами одного события — используйте его для идемпотентности на своей стороне.

Подпись

Каждый запрос несёт эти заголовки:

  • x-avp-signature — sha256=<hex>, где hex-значение — HMAC-SHA256 от сырого тела запроса с ключом-секретом вашей подписки.
  • x-avp-event — тип события, чтобы вы могли маршрутизировать до разбора тела.
  • x-avp-timestamp — когда доставка была отправлена.
  • x-avp-subscription-id — к какой подписке относится доставка.
  • x-avp-delivery-id — то же значение, что deliveryId в теле.

Проверяйте подпись на каждом запросе: вычислите HMAC от сырого тела со своим секретом и сравните с заголовком. Сравнение строк обязательно должно быть константным по времени — наивное == уязвимо к атакам по времени. Отклоняйте всё, что не совпало.

Повторы и надёжность

  • Доставка как минимум один раз: одно и то же событие может прийти повторно. Используйте deliveryId для идемпотентности.
  • Таймаут: 10 секунд. Если ваш эндпоинт отвечает дольше, доставка считается неудавшейся.
  • Политика повторов: первая попытка — сразу, затем 5 повторов с растущими интервалами (1 мин → 5 мин → 15 мин → 1 ч → 6 ч). После последнего повтора доставка отбрасывается и логируется.
  • Автоотключение: если подписка стабильно отказывает (50+ отброшенных доставок за 24 часа), платформа отключает её. После починки своего эндпоинта вы снова включаете её во вкладке Webhooks.

Вкладка Webhooks показывает журнал доставок по каждой подписке — каждую попытку, статус ответа, задержку, фрагмент ответа вашего эндпоинта. Есть и действие send test delivery, чтобы проверить эндпоинт до реального трафика.

Входящие вебхуки (обратное направление)

Вы можете и отправлять события внутрь живых разговоров. Создайте в проекте входящий вебхук с именем; платформа выдаст вам URL и отдельный секрет подписи (показывается один раз).

POST /v1/projects/{project_id}/webhooks/{name}
x-avp-signature: sha256=<hex-hmac-of-raw-body>
Content-Type: application/json

Подпишите сырое тело секретом входящего вебхука — той же схемой HMAC-SHA256, что и исходящие доставки. Тело доставляется в каждую сессию проекта, активную в момент запроса, как событие-интерцепт on_webhook_received; скрипт, привязанный к этому событию, читает тело и решает, что делать, — сообщить агенту посреди звонка, что заказ отправлен, передать изменение цены в идущую консультацию, запустить вызов инструмента извне.

Лимиты: 25 имён входящих вебхуков на проект. Запросы к несуществующему имени возвращают 404; сессии без обработчика on_webhook_received игнорируют событие.