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:
Проверка подписи
Каждый запрос содержит подпись HMAC-SHA256 для исходного тела запроса в заголовкеX-ThunderPhone-Signature. Ключ подписи — это
secret конечной точки (или secret вебхука на уровне организации для устаревших
доставок).
Шаги
- Прочитайте исходное тело запроса до любого парсинга.
- Вычислите
hmac_sha256(secret, body).hexdigest(). - Сравните за константное время с заголовком
X-ThunderPhone-Signature.
Семантика доставки
Эта семантика применяется к доставкам в конечные точки. Устаревший вебхук с одним 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-адреса
Исходные IP-адреса
Исходящие вебхуки поступают из диапазона облачных IP-адресов ThunderPhone.
Если для вашего файрвола требуется список разрешённых адресов, обратитесь в поддержку, и мы
предоставим актуальные диапазоны.
Выбор между устаревшими вебхуками и вебхуками на основе конечных точек
Новые интеграции должны получать события через вебхуки на основе конечных
точек. Сохраняйте (или добавляйте) устаревший URL, только если вы настраиваете звонки
динамически в момент приёма или используете вызов инструментов в режиме вебхука — эти
обмены запросами и ответами работают только через устаревший путь.
Связанные материалы
Каталог событий
Все типы событий и их полезные нагрузки.
Конечные точки вебхуков
Управляйте несколькими конечными точками, фильтрами событий и секретами.
telephony.incoming / web.incoming
Блокирующий запрос, на который ваш сервер должен ответить для настройки звонков.
telephony.complete / web.complete
Полезная нагрузка после звонка с расшифровкой, записью и метриками.