Skip to main content
ThunderPhone отправляет HTTP-запросы POST на ваш сервер, когда во время звонка происходят события: начинается входящий звонок, заканчивается звонок, завершается запуск оценки, срабатывает оповещение и так далее. Есть две модели доставки:

Конечные точки вебхуков (рекомендуется)

Несколько URL, секреты для каждой конечной точки, фильтры событий для каждой конечной точки и автоматические повторные попытки. Управление через GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Устаревший вебхук с одним URL

Один URL на организацию. Передаёт события жизненного цикла звонка, включая блокирующие обмены конфигурацией. Управляется через GET/PUT /v1/webhook.
Все десять типов событий из каталога событий доставляются через конечные точки вебхуков. Шесть событий жизненного цикла звонка (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) также отправляются в устаревший вебхук с одним URL — если у вас есть и устаревший URL, и подходящая конечная точка, вы получите событие по обоим путям. Блокирующее поведение (обмен конфигурацией telephony.incoming / web.incoming и диспетчеризация инструментов в режиме вебхуков) доступно исключительно по устаревшему пути; каждая доставка на конечную точку — это уведомление без ожидания ответа.

Формат полезной нагрузки

Доставки на конечные точки представляют собой JSON-объект с полями data, event_id и type:
event_id уникален для каждого отправленного события. Он остаётся одинаковым при повторных попытках и для каждой конечной точки, получающей событие — используйте его для дедупликации. Устаревший вебхук с одним URL отправляет те же type и data, но без event_id:
При передаче каждое тело сериализуется канонически — ключи отсортированы по алфавиту, без пробелов, в UTF-8. Примеры с форматированием в этой документации приведены только для удобства чтения. Полный список типов событий и полей полезной нагрузки смотрите в каталоге событий.

Проверка подписи

Каждый запрос содержит подпись HMAC-SHA256 для исходного тела запроса в заголовке X-ThunderPhone-Signature. Ключ подписи — это secret конечной точки (или secret вебхука на уровне организации для устаревших доставок).

Шаги

  1. Прочитайте исходное тело запроса до любого парсинга.
  2. Вычислите hmac_sha256(secret, body).hexdigest().
  3. Сравните за константное время с заголовком X-ThunderPhone-Signature.
Мы подписываем в точности те байты, которые отправляем, и эти байты представляют собой каноническую сериализацию JSON (отсортированные ключи, компактные разделители). Поэтому проверка по исходному телу всегда работает — а если ваш фреймворк предоставляет только распарсенный JSON, повторная сериализация с отсортированными ключами и компактными разделителями создаёт идентичные байты. Оба способа описаны в руководстве по проверке.

Семантика доставки

Эта семантика применяется к доставкам в конечные точки. Устаревший вебхук с одним URL выполняет одну синхронную попытку без повторов.
Каждое событие немедленно отправляется один раз. Любой ответ 2xx подтверждает доставку. При любом другом результате (не-2xx, ошибка соединения, тайм-аут) мы повторяем попытку через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч, 12 ч и 24 ч после первой попытки — всего 8 попыток в течение 24 часов. Если все попытки завершатся неудачно, доставка прекращается, а конечная точка помечается как status="failing" в конечных точках вебхуков. Верните 2xx, как только полезная нагрузка будет надёжно принята; обрабатывайте её асинхронно.
Порядок доставки обеспечивается по мере возможности. На практике мы доставляем события в порядке их создания, но повторные попытки могут изменить порядок при сбоях. Всегда выполняйте дедупликацию и сверяйте состояние по call_id / идентификатору объекта.
Доставка выполняется как минимум один раз: повторная попытка после ответа, который мы не получили, может создать дубликат события. Каждая повторная попытка содержит тот же event_id, поэтому сохраняйте обработанные идентификаторы и пропускайте повторы. event_id также используется всеми конечными точками — две конечные точки, подписанные на одно событие, получают одинаковый event_id.
Для доставки в конечные точки действует тайм-аут 30 с на каждую попытку. В устаревшем пути блокирующие запросы, определяющие поведение активного звонка — обмен конфигурацией telephony.incoming / web.incoming — завершаются по тайм-ауту через 10 с, однако медленный ответ задерживает приём звонка, поэтому стремитесь отвечать в течение нескольких секунд. Для вызова инструментов в режиме вебхука доступно 20 с.
Исходящие вебхуки поступают из диапазона облачных IP-адресов ThunderPhone. Если для вашего файрвола требуется список разрешённых адресов, обратитесь в поддержку, и мы предоставим актуальные диапазоны.

Выбор между устаревшими вебхуками и вебхуками на основе конечных точек

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

Связанные материалы

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

Все типы событий и их полезные нагрузки.

Конечные точки вебхуков

Управляйте несколькими конечными точками, фильтрами событий и секретами.

telephony.incoming / web.incoming

Блокирующий запрос, на который ваш сервер должен ответить для настройки звонков.

telephony.complete / web.complete

Полезная нагрузка после звонка с расшифровкой, записью и метриками.