Webhooks

Điểm cuối webhook

Quản lý nhiều URL webhook với secret riêng cho từng điểm cuối và bộ lọc sự kiện.

Hệ thống webhook dựa trên điểm cuối cho phép bạn đăng ký nhiều đích đến cho mỗi tổ chức, mỗi đích có secret, trạng thái và gói đăng ký riêng cho một tập hợp con các loại sự kiện. Đây là mô hình được khuyến nghị cho mọi tích hợp mới.

So sánh với webhook URL đơn cũ, được giữ lại để tương thích ngược nhưng chỉ hỗ trợ một URL cho mỗi tổ chức.

Điểm cuối#

Đối tượng điểm cuối#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Loại sự kiện hợp lệ#

events được xác thực theo đúng tập hợp này — giá trị ngoài danh sách sẽ trả về 400. Xem Danh mục sự kiện để biết cấu trúc payload của từng loại.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

Trạng thái điểm cuối#

• active — các lần phân phối diễn ra bình thường.
• disabled — tạm dừng thủ công qua PATCH. Không có yêu cầu nào được gửi. Chúng tôi không bao giờ thay đổi trạng thái của một điểm cuối disabled; việc chuyển lại thành active luôn do bạn quyết định.
• failing — được đặt tự động khi một lần phân phối đến điểm cuối dùng hết toàn bộ lịch thử lại (8 lần thử trong 24 giờ) mà không từng nhận được phản hồi 2xx. Điểm cuối lỗi sẽ không nhận thêm lưu lượng. Sau khi điểm cuối được khắc phục, hãy PATCH trạng thái về active; các lần phân phối chưa hết lịch thử lại sẽ tiếp tục từ vị trí đã dừng.

Liệt kê điểm cuối#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Trả về một mảng đối tượng điểm cuối.

Tạo endpoint#

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

Trường yêu cầu#

Trả về 201 Created cùng đối tượng Endpoint đã bổ sung trường secret cấp cao nhất chứa khóa ký thô — một chuỗi hex gồm 48 ký tự:

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

Cập nhật endpoint#

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

Trả về 200 OK cùng đối tượng Endpoint đã cập nhật.

Gửi thử một lần phân phối#

Gửi sự kiện webhook.test tổng hợp đến một endpoint thông qua quy trình phân phối thông thường, bao gồm tuần tự hóa JSON chuẩn, X-ThunderPhone-Signature, ghi nhận phân phối và theo dõi lượt thử lại. Lần kiểm thử nhắm đến endpoint đã chọn bất kể bộ lọc events của endpoint đó.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Endpoint nhận một envelope như sau:

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

API trả về 200 OK sau lần thử đầu tiên, ngay cả khi đích đến trả về lỗi. Kiểm tra success, status, response_code và error để biết kết quả phân phối:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test là sự kiện tổng hợp và không thể thêm vào gói đăng ký events của endpoint. Nếu lần thử đầu tiên thất bại, lần phân phối sẽ tuân theo cùng lịch thử lại như các lần phân phối sự kiện thông thường.

Xóa một endpoint#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Trả về 204 No Content. Việc phân phối đến URL sẽ dừng ngay lập tức; các lần thử lại đang thực hiện sẽ bị hủy.

Liên quan#