X-ThunderPhone-Signature. Xác thực đúng một lần rồi dùng cùng helper
cho mọi handler.
Thuật toán
- Đọc phần thân yêu cầu thô — chính xác các byte chúng tôi POST đến bạn.
- Tính
hmac_sha256(secret, body).hexdigest(). - So sánh theo thời gian hằng số với
X-ThunderPhone-Signature. (So sánh chuỗi thông thường làm lộ thông tin thời gian.)
, và : không có khoảng trắng), UTF-8. Điều này cung cấp cho bạn một cách
thứ hai hoàn toàn tương đương khi framework của bạn chỉ cung cấp JSON đã phân tích:
tuần tự hóa lại theo chuẩn rồi tính HMAC cho dữ liệu đó.
Dùng secret nào?
Lưu secret trong trình quản lý secret hoặc biến môi trường — không bao giờ commit secret đó.
Các cách triển khai tham khảo
Cả bốn cách đều xác thực phần thân yêu cầu thô:Kết nối theo framework cụ thể
Xác minh lệnh gọi công cụ
Khi tác nhân AI gọi trực tiếp một trong các công cụ hàm của bạn (công cụ cóendpoint), yêu cầu sẽ mang hai header ThunderPhone bên cạnh
endpoint.headers bạn đã cấu hình:
X-ThunderPhone-Call-ID— id dạng số của cuộc gọi đang diễn ra.X-ThunderPhone-Signature— HMAC-SHA256, sử dụng secret webhook cấp tổ chức của bạn làm khóa, trên chính xác các byte của phần thân yêu cầu.
verify() hoạt động không thay đổi, với hai điểm cần lưu ý:
- Công cụ
GET/DELETEkhông có phần thân. Đối số được truyền dưới dạng tham số truy vấn và chữ ký được tính trên chuỗi byte rỗng — do đó dùngverify(b"", sig, secret)(Python) hoặcverify(Buffer.alloc(0), sig, secret)(Node). Không hash chuỗi truy vấn. - Tổ chức không cấu hình webhook cũ sẽ không có secret cấp tổ chức. Trong
trường hợp đó, lệnh gọi công cụ chỉ mang
X-ThunderPhone-Call-IDvà không có header chữ ký. Cấu hình webhook cũ (PUT /v1/webhook) để có secret ký, hoặc xác thực lệnh gọi công cụ bằng header riêng của bạn quaendpoint.headers.
endpoint, được gửi
đến webhook tổ chức của bạn dưới dạng telephony.tool / web.tool) là một webhook
được ký thông thường — áp dụng quy trình chuẩn ở trên. Xem
Công cụ hàm để biết cả hai dạng yêu cầu.
Các lỗi thường gặp
Tuần tự hóa lại với định dạng mặc định
Tuần tự hóa lại với định dạng mặc định
Phân tích body rồi xuất lại bằng các thiết lập mặc định của thư viện JSON
(dấu cách sau
, / :, khóa theo thứ tự chèn) sẽ tạo ra
byte khác và làm HMAC không hợp lệ. Xác minh body thô — hoặc nếu
bắt buộc phải tuần tự hóa lại, hãy khớp chính xác định dạng chuẩn của chúng tôi: khóa được sắp xếp,
dấu phân cách gọn, UTF-8.Framework tự động phân tích JSON
Framework tự động phân tích JSON
Middleware
express.json() của Express tiêu thụ luồng body
khiến bạn mất các byte thô. Dùng express.raw() riêng cho route webhook,
hoặc đệm body thô trong một middleware tiền xử lý.
NestJS / Koa cũng tương tự — hãy xem tài liệu về “raw body” của chúng.So sánh không an toàn theo thời gian
So sánh không an toàn theo thời gian
expected === signature trong JS hoặc expected == signature trong
Python là các phép so sánh có thời gian thay đổi. Hãy dùng crypto.timingSafeEqual
hoặc hmac.compare_digest tương ứng. Chênh lệch hiệu năng
là không đáng kể.Dùng sai secret cho endpoint công cụ
Dùng sai secret cho endpoint công cụ
Các lệnh gọi trực tiếp đến endpoint công cụ được ký bằng webhook
secret cấp tổ chức (
GET /v1/webhook) — không phải bằng bất kỳ secret riêng theo endpoint nào
từ /v1/developer/webhook-endpoints. Dùng lại cùng hàm verify()
nhưng hãy đảm bảo truyền secret của tổ chức vào hàm đó trên các route công cụ.Băm chuỗi truy vấn trên công cụ GET/DELETE
Băm chuỗi truy vấn trên công cụ GET/DELETE
Với các phương thức công cụ không có body, chữ ký bao phủ chuỗi byte
rỗng, giúp duy trì một công thức chung: HMAC body yêu cầu thô,
bất kể đó là gì. Băm URL hoặc chuỗi truy vấn sẽ không bao giờ khớp.
Không trả về 401 khi không khớp
Không trả về 401 khi không khớp
Trả về 200 khi xác minh thất bại khiến handler trở thành mục tiêu
phát lại. Luôn phản hồi mã không thuộc nhóm 2xx nếu xác minh thất bại.
Bước tiếp theo
Tổng quan về webhook
Ngữ nghĩa phân phối, thử lại, IP nguồn.
Endpoint webhook
Quản lý nhiều URL, xoay vòng secret.
Công cụ hàm
Hai luồng gọi công cụ và cấu trúc yêu cầu của chúng.
Tích hợp công cụ
Xây dựng một tích hợp hoàn chỉnh sử dụng công cụ từ đầu đến cuối.