Tổng quan về Webhook

Cách ThunderPhone gửi sự kiện theo thời gian thực, cách xác minh chữ ký và so sánh mô hình gửi cũ với mô hình gửi dựa trên endpoint.

ThunderPhone gửi yêu cầu HTTP POST đến máy chủ của bạn khi các sự kiện xảy ra trong cuộc gọi — cuộc gọi đến bắt đầu, cuộc gọi kết thúc, một lần chấm điểm hoàn tất, một cảnh báo được kích hoạt, v.v. Có hai mô hình phân phối:

Mọi loại sự kiện được liệt kê trong danh mục sự kiện đều được gửi qua điểm cuối webhook. Sáu sự kiện trong vòng đời cuộc gọi (telephony.incoming, telephony.complete, telephony.tool, web.incoming, web.complete, web.tool) cũng được gửi đến webhook kế thừa một URL — nếu bạn có cả URL kế thừa và một điểm cuối khớp, bạn sẽ nhận sự kiện trên cả hai đường dẫn. Hành vi chặn (gồm trao đổi cấu hình telephony.incoming / web.incoming và điều phối công cụ ở chế độ webhook) chỉ có trên đường dẫn kế thừa; mọi lần gửi đến điểm cuối đều là thông báo gửi đi mà không chờ phản hồi.

Định dạng payload#

Các lần gửi đến điểm cuối là một đối tượng JSON có data, event_id và type:

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

event_id là duy nhất cho mỗi sự kiện được phát ra. Giá trị này giống hệt giữa các lần thử lại và giữa mọi điểm cuối nhận sự kiện — hãy dùng giá trị này để loại bỏ trùng lặp.

Webhook kế thừa một URL gửi cùng type và data nhưng không có event_id:

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

Trên đường truyền, mọi phần thân đều được tuần tự hóa theo chuẩn — các khóa được sắp xếp theo thứ tự bảng chữ cái, không có khoảng trắng, UTF-8. Các ví dụ được định dạng đẹp trong tài liệu này chỉ nhằm mục đích dễ đọc.

Xem Danh mục sự kiện để biết danh sách đầy đủ các loại sự kiện và trường payload.

Xác minh chữ ký#

Mỗi yêu cầu đều mang hai chữ ký, cả hai đều dùng HMAC-SHA256 với khóa là secret của endpoint (hoặc secret webhook cấp tổ chức của bạn đối với các lần gửi cũ):

• X-ThunderPhone-Signature-V2: t=<unix seconds>,v1=<hex> ký dấu thời gian, phương thức, đường dẫn và truy vấn, cùng phần thân thô. Xác minh chữ ký này và từ chối các yêu cầu có t chênh lệch quá 5 phút so với đồng hồ của bạn để yêu cầu bị chặn không thể bị phát lại sau đó. Các lần thử lại được ký lại khi gửi.
• X-ThunderPhone-Signature chỉ ký phần thân thô. Chữ ký này vẫn được gửi, không thay đổi, để các trình xác minh hiện có tiếp tục hoạt động.

Các bước#

1. Đọc header, phương thức, đường dẫn và truy vấn thô, cùng phần body thô trước khi thực hiện bất kỳ quá trình phân tích nào.
2. Tính HMAC-SHA256 dạng hex của <t>\n<METHOD>\n<path and query>\n<body> bằng secret của bạn.
3. Từ chối yêu cầu nếu t lệch quá 300 giây hoặc nếu kết quả không khớp với v1 trong phép so sánh thời gian hằng số.

Body là bản tuần tự hóa JSON chuẩn (khóa được sắp xếp, dấu phân cách gọn), và chúng tôi ký chính xác các byte được truyền đi. Hướng dẫn xác minh có chuỗi đã ký chính xác, ví dụ hoàn chỉnh, mã không dùng SDK và header cũ.

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);
  },
);

Ngữ nghĩa phân phối#

Các ngữ nghĩa này áp dụng cho lần gửi đến endpoint. Webhook URL đơn lẻ cũ là một lần thử đồng bộ duy nhất không có lần thử lại, ngoại trừ trao đổi cấu hình telephony.incoming cho cuộc gọi điện thoại, được thử lại một lần.

Chọn giữa webhook cũ và webhook dựa trên endpoint#

Các tích hợp mới nên tiêu thụ sự kiện qua webhook dựa trên endpoint. Chỉ giữ lại (hoặc thêm) URL cũ nếu bạn cấu hình cuộc gọi động tại thời điểm nhận cuộc gọi hoặc sử dụng điều phối công cụ ở chế độ webhook — các trao đổi yêu cầu/phản hồi đó chỉ chạy trên đường dẫn cũ.

Liên quan#