Điểm cuối webhook

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 riêng, trạng thái riêng 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 một URL cũ, được duy trì để tương thích ngược nhưng chỉ hỗ trợ một URL cho mỗi tổ chức.

Điểm cuối

Phương thức	Đường dẫn	Vai trò bắt buộc	Mô tả
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Liệt kê điểm cuối
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Tạo điểm cuối
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Cập nhật nhãn / URL / sự kiện / trạng thái
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Xóa điểm cuối
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Gửi bản phân phối kiểm thử đã ký

Đố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"
}

Trường	Loại	Mô tả
`id`	UUID	ID điểm cuối
`label`	string	Tên hiển thị, 1–120 ký tự
`url`	string	URL HTTPS; cho phép `http://localhost` để phát triển
`events`	mảng string	Các loại sự kiện đã đăng ký (xem giá trị hợp lệ). Mảng rỗng đăng ký tất cả sự kiện
`status`	string	`active`, `disabled` (tạm dừng thủ công), hoặc `failing` (tự động đặt khi một lần phân phối dùng hết lịch thử lại 24 giờ mà không có một phản hồi 2xx nào)
`secret_hint`	string	4 ký tự đầu và 4 ký tự cuối của secret ký với dấu ba chấm (`a1b2…9f0e`) — đủ để đối chiếu với secret bạn đã lưu cục bộ mà không làm lộ toàn bộ giá trị
`created_at`, `updated_at`	dấu thời gian

secret đầy đủ của điểm cuối chỉ được trả về một lần khi tạo và sẽ không bao giờ được trả về lại. Lưu trữ an toàn — nếu làm mất, hãy xóa điểm cuối và tạo lại.

Các loại sự kiện hợp lệ

events được xác thực theo đúng tập hợp này — các 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
web.incoming, web.complete, web.tool
call.graded
issue.reported
test-call.completed
alert.triggered

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

active — các bả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 gặp lỗi sẽ không nhận thêm lưu lượng nào. Sau khi sửa điểm cuối, hãy PATCH trạng thái của nó trở lại active; các bản phân phối có lịch thử lại chưa hết 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ường	Kiểu	Bắt buộc	Mô tả
`label`	string	có	1–120 ký tự
`url`	string	có	URL HTTPS (`http` chỉ được phép cho `localhost` / `127.0.0.1`)
`events`	array	không	Để trống hoặc bỏ qua sẽ đăng ký tất cả sự kiện. Phải dùng các giá trị liệt kê trong Loại sự kiện hợp lệ; các giá trị trùng lặp sẽ bị loại bỏ

Trả về 201 Created cùng đối tượng Endpoint và một trường secret cấp cao nhất bổ sung 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"
}

secret chỉ được trả về khi tạo. Các phản hồi GET tiếp theo chỉ bao gồm secret_hint. Sao chép toàn bộ giá trị vào trình quản lý secret của bạn trước khi đóng phản hồi.

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ường	Kiểu	Mô tả
`label`	string
`url`	string
`events`	array
`status`	string	`active` hoặc `disabled`. Đặt thành `active` để bật lại endpoint mà máy chủ đã đánh dấu là `failing`

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

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

Gửi sự kiện webhook.test tổng hợp đến một endpoint bằng pipeline 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 lần phân phối và theo dõi 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 được 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ể được 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 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 gửi đến URL dừng ngay lập tức; các lần thử lại đang diễn ra sẽ bị hủy.

Liên quan

Danh mục sự kiện

Danh sách đầy đủ các giá trị events mà bạn có thể đăng ký nhận.

Tổng quan về webhook

Xác minh chữ ký và ngữ nghĩa phân phối.

Webhooks

Function Tools

Điểm cuối

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

Các loại sự kiện hợp lệ

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

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

Tạo endpoint

Trường yêu cầu

Cập nhật endpoint

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

Xóa endpoint

Liên quan

Danh mục sự kiện

Tổng quan về webhook

​Điểm cuối

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

​Các loại sự kiện hợp lệ

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

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

​Tạo endpoint

​Trường yêu cầu

​Cập nhật endpoint

​Gửi một lần phân phối kiểm thử

​Xóa endpoint

​Liên quan

Danh mục sự kiện

Tổng quan về webhook

Điểm cuối

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

Các loại sự kiện hợp lệ

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

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

Tạo endpoint

Trường yêu cầu

Cập nhật endpoint

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

Xóa endpoint

Liên quan