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 с, але повільна відповідь затримує прийняття дзвінка,
тому намагайтеся відповідати протягом кількох секунд. Надсилання інструментів у режимі вебхуків
tool dispatch допускає 20 с.Вихідні IP-адреси
Вихідні IP-адреси
Вихідні вебхуки надходять із хмарного діапазону IP-адрес ThunderPhone.
Якщо ваш брандмауер потребує списку дозволених адрес, зверніться до служби підтримки, і ми
надамо актуальні діапазони.
Вибір між застарілими вебхуками та вебхуками з кінцевими точками
Нові інтеграції мають отримувати події через вебхуки з кінцевими точками.
Зберігайте (або додайте) застарілу URL-адресу, лише якщо ви динамічно налаштовуєте дзвінки
під час прийняття або використовуєте надсилання інструментів у режимі вебхуків — ці
обміни запитами й відповідями працюють лише за застарілим шляхом.
Пов’язані матеріали
Каталог подій
Усі типи подій і їхні дані.
Кінцеві точки вебхуків
Керуйте кількома кінцевими точками, фільтрами подій і секретами.
telephony.incoming / web.incoming
Блокувальний запит, на який ваш сервер має відповісти для налаштування дзвінків.
telephony.complete / web.complete
Дані після дзвінка з транскриптом, записом і метриками.