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.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
và đ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_id và
type:
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 và 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 type và data nhưng không có
event_id:
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 headerX-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
- Đọc nội dung yêu cầu thô trước khi phân tích cú pháp.
- Tính
hmac_sha256(secret, body).hexdigest(). - So sánh theo thời gian hằng với header
X-ThunderPhone-Signature.
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.Thử lại
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ự
Thứ tự
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.Bản sao
Bản sao
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.Thời gian chờ
Thời gian chờ
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.IP nguồn
IP nguồn
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ố.