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 с, але повільна відповідь затримує прийняття дзвінка, тому намагайтеся відповідати протягом кількох секунд. Надсилання інструментів у режимі вебхуків tool dispatch допускає 20 с.
Вихідні вебхуки надходять із хмарного діапазону IP-адрес ThunderPhone. Якщо ваш брандмауер потребує списку дозволених адрес, зверніться до служби підтримки, і ми надамо актуальні діапазони.

Вибір між застарілими вебхуками та вебхуками з кінцевими точками

Нові інтеграції мають отримувати події через вебхуки з кінцевими точками. Зберігайте (або додайте) застарілу URL-адресу, лише якщо ви динамічно налаштовуєте дзвінки під час прийняття або використовуєте надсилання інструментів у режимі вебхуків — ці обміни запитами й відповідями працюють лише за застарілим шляхом.

Пов’язані матеріали

Каталог подій

Усі типи подій і їхні дані.

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

Керуйте кількома кінцевими точками, фільтрами подій і секретами.

telephony.incoming / web.incoming

Блокувальний запит, на який ваш сервер має відповісти для налаштування дзвінків.

telephony.complete / web.complete

Дані після дзвінка з транскриптом, записом і метриками.