Đ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 endpoint 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.

Endpoint#

Đối tượng endpoint#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "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 — 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, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (đã dành riêng; chưa được phát ra)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated không có ngữ cảnh tác nhân AI và chỉ được gửi đến các endpoint trên toàn tổ chức.

Không thể chọn rõ ràng voice.ready và voice.failed. Để nhận các sự kiện này, hãy tạo endpoint trên toàn tổ chức với events: []. Danh sách sự kiện trống nhận mọi sự kiện được hỗ trợ, ngoại trừ telephony.turn và web.turn, vốn phải được chọn rõ ràng.

Trạng thái endpoint#

• active — các lần gửi được thực hiện bình thường.
• disabled — được tạm dừng thủ công qua PATCH. Không có request nào được gửi. Chúng tôi không bao giờ thay đổi trạng thái của endpoint disabled; việc chuyển lại về active luôn do bạn quyết định.
• failing — được đặt tự động khi một lần gửi đến endpoint sử 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 mã 2xx. Endpoint ở trạng thái lỗi sẽ không nhận thêm lưu lượng truy cập. Chúng tôi gửi email cho chủ sở hữu và quản trị viên của tổ chức bạn khi điều này xảy ra, và dashboard hiển thị endpoint đã tạm dừng cùng nút Kích hoạt lại. Sau khi endpoint được khắc phục, PATCH trạng thái của endpoint về active; các lần gửi có lịch thử lại chưa hết hạn sẽ tiếp tục từ vị trí đã dừng.

Liệt kê endpoint#

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 Endpoint. Truyền ?agent_id=42 để chỉ trả về các endpoint áp dụng cho tác nhân AI đó.

Endpoint áp dụng cho tác nhân AI#

Endpoint trên toàn tổ chức nhận mọi sự kiện khớp. Endpoint có agent_id chỉ nhận các sự kiện khớp cho cuộc gọi do tác nhân AI đó xử lý; các sự kiện không có ngữ cảnh tác nhân AI, chẳng hạn như alert.triggered, sẽ không bao giờ đến đó. Bạn cũng có thể tạo và quản lý các endpoint này từ mục Webhook của trình xây dựng tác nhân AI.

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 và một trường secret cấp cao 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"
}

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.

Luân chuyển bí mật ký#

Thay thế bí mật ký của một điểm cuối, ví dụ khi bí mật bị mất hoặc có thể đã bị lộ. Với điểm cuối thuộc phạm vi tác nhân AI, bạn cũng có thể sử dụng bảng điều khiển: mở mục Webhook của tác nhân AI và chọn Tạo lại bí mật trên điểm cuối. Các điểm cuối trên toàn tổ chức được luân chuyển thông qua API.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Trả về 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

Gửi lần gửi thử nghiệm#

Gửi một sự kiện webhook.test tổng hợp đến một endpoint bằng quy trình phân phối thông thường, bao gồm tuần tự hóa JSON chuẩn tắc, cả hai header chữ ký, ghi nhận phân phối và theo dõi việc thử lại. Bài kiểm tra 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 phong bì dữ liệu 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 trả về lỗi. Kiểm tra success, status, response_code và error để biết kết quả gử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 mô phỏng 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, ThunderPhone sẽ thử lại một lần sau khoảng một phút rồi dừng; lần gửi sau đó hiển thị status: "failed" trong Gỡ lỗi lần gửi. Lần gửi thử nghiệm không bao giờ đánh dấu endpoint là failing.

Để cấu hình trình kích hoạt dựa trên cấu trúc sự kiện thực, hãy truyền event_type tùy chọn. Lần gửi vẫn là mô phỏng và chứa "sample": true; mẫu liên quan đến cuộc gọi sử dụng call_id: 0 và agent_id: 0.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type chấp nhận bất kỳ giá trị nào trong Loại sự kiện hợp lệ. Việc bỏ qua trường này sẽ giữ nguyên hành vi webhook.test chung.

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 sẽ dừng ngay lập tức; các lần thử lại đang diễn ra sẽ bị hủy.

Gỡ lỗi lần gửi#

Trước khi kết luận rằng webhook chưa được gửi, hãy kiểm tra GET /v1/developer/webhook-deliveries. API này hiển thị các lần thử gần đây từ cả hai hệ thống webhook, bao gồm ID cuộc gọi, nguồn gốc URL, trạng thái HTTP, số lần thử, danh mục lỗi trong danh sách cho phép và thời điểm thử lại tiếp theo. API này không bao giờ trả về payload sự kiện, bản chép lời, nội dung lỗi đã lưu, nội dung phản hồi hoặc đường dẫn URL.

Bạn cũng có thể xem cùng lịch sử gần đây trong Tác nhân → chọn một tác nhân → Webhook → Lần gửi gần đây. Các hàng hiển thị nhãn endpoint và nguồn gốc URL được dùng trong lần thử mới nhất. Đây là trạng thái vận hành thay vì nhật ký kiểm toán bất biến: việc xóa endpoint cũng xóa các hàng lần gửi của endpoint đó.

Đối với lỗi 404 của n8n, trước tiên hãy xác nhận workflow đang hoạt động, chấp nhận POST và sử dụng URL webhook production thay vì URL thử nghiệm. Lỗi 401 hoặc 403 cho thấy vấn đề về xác thực hoặc xác minh chữ ký; hết thời gian chờ cho thấy độ trễ hoặc khả năng sẵn sàng của đích; lỗi TLS cho thấy vấn đề về chuỗi chứng chỉ, tên máy chủ hoặc ngày hết hạn.

Liên quan#