Skip to main content
ThunderPhone gửi yêu cầu HTTP POST đến máy chủ của bạn khi có sự kiện xảy ra trong một cuộc gọi — một cuộc gọi đến bắt đầu, một cuộc gọi kết thúc, một lượt 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 gửi:

Endpoint webhook (khuyến nghị)

Nhiều URL, secret cho từng endpoint, bộ lọc sự kiện cho từng endpoint, và tự động thử lại. Quản lý qua GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints.

Webhook cũ một URL

Một URL cho mỗi tổ chức. Chứa các sự kiện trong vòng đời cuộc gọi, bao gồm các trao đổi cấu hình chặn. Quản lý tại GET/PUT /v1/webhook.
Cả mười loại sự kiện trong danh mục sự kiện đều được gửi qua endpoint 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 cũ một URL — nếu bạn có cả URL cũ và một endpoint khớp, bạn sẽ nhận sự kiện trên cả hai đường dẫn. Hành vi chặn (bao gồm trao đổi cấu hình telephony.incoming / web.incomingđiều phối công cụ ở chế độ webhook) chỉ có trên đường dẫn cũ; mọi lần gửi đến endpoint đều là thông báo gửi đi không chờ phản hồi.

Định dạng payload

Các lần gửi đến endpoint là một đối tượng JSON có data, event_idtype:
event_id là duy nhất cho mỗi sự kiện được phát sinh. Giá trị này giống nhau trong các lần thử lại trên mọi endpoint nhận sự kiện — hãy khử trùng lặp dựa trên giá trị này. Webhook cũ một URL gửi cùng typedata nhưng không có event_id:
Khi truyền đi, mọi body được tuần tự hóa theo chuẩn tắc — các khóa được sắp xếp theo thứ tự 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 chữ ký HMAC-SHA256 của nội dung yêu cầu thô trong header X-ThunderPhone-Signature. Khóa ký là secret của endpoint (hoặc secret webhook cấp tổ chức của bạn cho các lần gửi cũ).

Các bước

  1. Đọc nội dung yêu cầu thô trước khi phân tích cú pháp.
  2. Tính hmac_sha256(secret, body).hexdigest().
  3. So sánh theo thời gian hằng với header X-ThunderPhone-Signature.
Chúng tôi ký chính xác các byte được truyền đi, và các byte đó 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ì vậy, việc xác minh dựa trên nội dung thô luôn hoạt động — và nếu framework của bạn chỉ cung cấp JSON đã được phân tích cú pháp, việc tuần tự hóa lại với khóa được sắp xếp và dấu phân cách gọn sẽ tạo ra các byte giống hệt. Cả hai cách đều được trình bày trong hướng dẫn xác minh.

Ngữ nghĩa phân phối

Các ngữ nghĩa này áp dụng cho việc phân phố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.
Mỗi sự kiện được thử gửi ngay một lần. Mọi phản hồi 2xx đều xác nhận việc phân phối. Với bất kỳ kết quả nào khác (không phải 2xx, lỗi kết nối, hết thời gian chờ), chúng tôi sẽ thử lại sau 1 phút, 5 phút, 30 phút, 2 giờ, 6 giờ, 12 giờ và 24 giờ kể từ lần thử đầu tiên — 8 lần thử trong 24 giờ. Nếu mọi lần thử đều thất bại, việc phân phối sẽ dừng và endpoint được đánh dấu status="failing" trong webhook endpoint. Hãy trả về 2xx ngay khi payload được chấp nhận và lưu bền vững; xử lý bất đồng bộ.
Thứ tự phân phối được thực hiện theo nỗ lực tối đa. Trên thực tế, chúng tôi phân phối theo thứ tự các sự kiện được phát ra, nhưng việc thử lại có thể làm thay đổi thứ tự khi xảy ra lỗi. Luôn khử trùng lặp và đối soát theo call_id / id đối tượng.
Phân phối là ít nhất một lần: việc thử lại sau một phản hồi mà chúng tôi không nhận được có thể tạo bản sao của sự kiện. Mỗi lần thử lại mang cùng event_id, vì vậy hãy lưu id đã xử lý và bỏ qua các lần lặp. event_id cũng được dùng chung giữa các endpoint — hai endpoint đăng ký cùng một sự kiện sẽ nhận cùng event_id.
Việc phân phối đến endpoint có thời gian chờ 30 giây cho mỗi lần thử. Trên đường dẫn cũ, các yêu cầu chặn điều khiển hành vi cuộc gọi trực tiếp — trao đổi cấu hình telephony.incoming / web.incoming — sẽ hết thời gian chờ sau 10 giây, nhưng phản hồi chậm sẽ trì hoãn việc nhận cuộc gọi, vì vậy hãy cố gắng phản hồi trong vài giây. Điều phối công cụ ở chế độ webhook cho phép 20 giây.
Webhook gửi đi bắt nguồn từ dải IP đám mây của ThunderPhone. Nếu tường lửa của bạn yêu cầu danh sách cho phép, hãy liên hệ bộ phận hỗ trợ và chúng tôi sẽ chia sẻ các dải hiện tại.

Lựa chọn giữa webhook cũ và webhook dựa trên endpoint

Các tích hợp mới nên tiếp nhận sự kiện thông 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

Danh mục sự kiện

Tất cả loại sự kiện và payload của chúng.

Webhook endpoint

Quản lý nhiều endpoint, bộ lọc sự kiện và secret.

telephony.incoming / web.incoming

Yêu cầu chặn mà server của bạn phải phản hồi để cấu hình cuộc gọi.

telephony.complete / web.complete

Payload sau cuộc gọi kèm bản chép lời, bản ghi âm và chỉ số.