Огляд вебхуків

Як ThunderPhone надсилає події в реальному часі, як перевіряти підписи та як порівнюються застаріла й кінцева моделі доставки.

ThunderPhone надсилає HTTP-запити POST на ваш сервер, коли під час дзвінка відбуваються події — починається вхідний дзвінок, завершується дзвінок, завершується перевірка оцінювання, спрацьовує сповіщення тощо. Є дві моделі доставки:

Усі перелічені типи подій у каталозі подій доставляються через кінцеві точки вебхуків. Шість подій життєвого циклу дзвінка (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) також надсилаються до застарілого вебхука з однією URL-адресою — якщо у вас є і застаріла URL-адреса, і відповідна кінцева точка, ви отримуєте подію за обома шляхами. Блокувальна поведінка (обмін конфігурацією telephony.incoming / web.incoming та виклик інструментів у режимі вебхуків) доступна виключно через застарілий шлях; кожна доставка до кінцевої точки є сповіщенням без очікування відповіді.

Формат корисного навантаження#

Доставки до кінцевих точок містять JSON-об’єкт із data, event_id та type:

{
  "data": {
    "call_id": 987654321,
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  },
  "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11",
  "type": "telephony.incoming"
}

event_id є унікальним для кожної надісланої події. Він однаковий для повторних спроб і для кожної кінцевої точки, що отримує подію — виконуйте дедуплікацію за ним.

Застарілий вебхук з однією URL-адресою надсилає ті самі type і data, але без event_id:

{
  "type": "telephony.incoming",
  "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }
}

Під час передавання кожне тіло серіалізується канонічно — ключі відсортовано за алфавітом, без пробілів, UTF-8. Відформатовані приклади в цій документації наведено лише для зручності читання.

Перегляньте каталог подій, щоб отримати повний список типів подій і полів корисного навантаження.

Перевірка підпису#

Кожен запит містить два підписи, обидва HMAC-SHA256 з ключем secret кінцевої точки (або secret вебхука на рівні вашої організації для застарілих доставок):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> підписує часову позначку, метод, шлях і параметри запиту, а також необроблене тіло. Перевіряйте цей підпис і відхиляйте запити, у яких t відрізняється від вашого часу більш ніж на 5 хвилин, щоб перехоплений запит не можна було відтворити пізніше. Повторні спроби підписуються повторно під час надсилання.
• X-ThunderPhone-Signature підписує лише необроблене тіло. Його й надалі надсилають без змін, щоб наявні засоби перевірки продовжували працювати.

Кроки#

1. Зчитайте заголовок, метод, необроблений шлях і параметри запиту, а також необроблене тіло до будь-якого аналізу.
2. Обчисліть шістнадцяткове значення HMAC-SHA256 для <t>\n<METHOD>\n<path and query>\n<body> за допомогою вашого секрету.
3. Відхиліть запит, якщо t відхиляється більш ніж на 300 секунд або якщо результат не збігається з v1 під час порівняння за сталий час.

Тіла запитів є канонічною серіалізацією JSON (відсортовані ключі, компактні роздільники), і ми підписуємо саме ті байти, які передаємо. Посібник із перевірки містить точний підписуваний рядок, приклад із розрахунком, код без SDK і застарілий заголовок.

from flask import Flask, abort, request
from thunderphone import verify_signature
 
app = Flask(__name__)
 
@app.post("/thunderphone-webhook")
def handle():
    query = request.query_string.decode()
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=WEBHOOK_SECRET,
        method=request.method,
        path=request.path + (f"?{query}" if query else ""),
        body=request.get_data(),  # raw bytes
    ):
        abort(401)
    event = request.get_json()
    # dispatch on event["type"] …
    return "", 204

import express from "express";
import { verifySignature } from "@thunderphone/sdk";
 
const app = express();
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifySignature({
      header: req.header("X-ThunderPhone-Signature-V2"),
      secret: process.env.WEBHOOK_SECRET,
      method: req.method,
      path: req.originalUrl,
      body: req.body,
    });
    if (!ok) return res.sendStatus(401);
    const event = JSON.parse(req.body.toString("utf8"));
    // dispatch on event.type …
    res.sendStatus(204);
  },
);

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

Ця семантика застосовується до доставок кінцевих точок. Застарілий вебхук з однією URL-адресою виконує одну синхронну спробу без повторних спроб, за винятком обміну конфігурацією телефонного дзвінка telephony.incoming, який повторюється один раз.

Вибір між застарілими вебхуками та вебхуками на основі ендпойнтів#

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

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