Open in
Webhook 端點
透過各端點專屬密鑰及事件篩選器,管理多個 webhook URL。
以端點為基礎的 webhook 系統讓你可為每個組織登記多個 目的地;每個目的地均有其專屬密鑰、狀態,以及對部分事件類型的訂閱。這是所有新整合建議採用的模式。
請與舊版單一 URL webhook比較, 後者為保持向後兼容而保留,但每個組織只支援一個 URL。
端點
| 方法 | 路徑 | 所需角色 | 說明 |
|---|---|---|---|
GET | /v1/developer/webhook-endpoints | admin+ | 列出端點 |
POST | /v1/developer/webhook-endpoints | admin+ | 建立端點 |
PATCH | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | 更新標籤/URL/事件/狀態 |
DELETE | /v1/developer/webhook-endpoints/{endpoint_id} | admin+ | 刪除端點 |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret | admin+ | 更換簽署密鑰 |
POST | /v1/developer/webhook-endpoints/{endpoint_id}/test | admin+ | 傳送已簽署的測試傳送項目 |
GET | /v1/developer/webhook-deliveries | admin+ | 檢查近期端點及舊版傳送結果 |
端點物件
{
"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"
}| 欄位 | 類型 | 說明 |
|---|---|---|
id | UUID | Endpoint ID |
label | string | 顯示名稱,1–120 個字元 |
url | string | HTTPS URL;開發環境可使用 http://localhost |
events | array of string | 已訂閱的事件類型(請參閱有效值)。空陣列會訂閱所有事件,惟明確訂閱專用事件除外(telephony.turn / web.turn / call.status_changed) |
status | string | active、disabled(手動暫停)或 failing(當一次傳送在 24 小時重試排程結束前未曾獲得任何 2xx 回應時自動設定) |
agent_id | integer | null | 此 Endpoint 所屬的智能體;null 表示整個機構適用 |
agent_name | string | null | 所屬智能體的名稱;如為整個機構適用的 Endpoint 則為 null |
secret_hint | string | 簽署密鑰的首 4 個及末 4 個字元,並以省略號顯示(a1b2…9f0e)——足以讓你對照本機儲存的密鑰,同時不會公開完整值 |
paused_at | timestamp | null | ThunderPhone 將 Endpoint 設為 failing 的時間。當狀態為 active 或 disabled 時為 null |
pause_last_error | string | Endpoint 暫停時的最後一次傳送錯誤,例如 HTTP 503: Service Unavailable。除非狀態為 failing,否則為空白 |
pause_undelivered_count | integer | null | Endpoint 自上次成功傳送後未能傳送的事件數目,於暫停時統計 |
created_at, updated_at | timestamp |
有效事件類型
events 會根據以下完全一致的集合驗證——清單以外的值會
回傳 400。各類型的 payload 結構請參閱事件目錄。
telephony.incoming,telephony.complete,telephony.tool,telephony.turnweb.incoming,web.complete,web.tool,web.turnsms.sent,sms.failedsms.received(保留;尚未發出)scheduled.skipped,scheduled.failedcall.graded,call.data_extracted,call.transfer_completed,call.status_changedcampaign.completedissue.reported,issue.escalatedtest-call.completedalert.triggeredphone_number.spam_risk_changed
issue.escalated 及 phone_number.spam_risk_changed 不包含智能體內容,並且
只會傳送至全機構端點。
無法明確選擇 voice.ready 及 voice.failed。如要接收
這些事件,請建立一個 events: [] 的全組織端點。空白事件
清單會接收所有支援的事件,但 telephony.turn、web.turn 及
call.status_changed 除外;這些事件必須明確選擇。
端點狀態
active—— 傳送正常進行。disabled—— 透過PATCH手動暫停。不會發送任何請求。我們 絕不會更改disabled端點的狀態;是否將其重新切換為active,一律由你決定。failing—— 當傳送至端點的請求用盡整個重試排程(24 小時內嘗試 8 次) 且始終未收到 2xx 回應時,系統會自動設定此狀態。處於失敗狀態的端點不會再收到任何流量。 發生此情況時,我們會向你組織的擁有人及管理員發送電郵, 而控制台會顯示已暫停的端點及「重新啟用」按鈕。 修正端點後,透過PATCH將其狀態改回active; 尚未用盡重試排程的傳送會從中斷處繼續。
列出端點
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"回傳一個端點物件陣列。
傳入 ?agent_id=42,只會回傳屬於該智能體的端點。
智能體範圍端點
整個機構範圍的端點會接收所有相符事件。設有
agent_id 的端點只會接收由該智能體處理的通話之相符事件;
沒有智能體內容的事件(例如 alert.triggered)絕不會傳送至該端點。你亦可在智能體建立工具的
網絡掛鈎部分建立及管理這些端點。
建立端點
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"]請求欄位
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
label | 字串 | 是 | 1–120 個字元 |
url | 字串 | 是 | HTTPS URL(僅 localhost / 127.0.0.1 允許使用 http) |
events | 陣列 | 否 | 留空或省略即訂閱除 telephony.turn / web.turn / call.status_changed 以外的所有事件;這些事件需要明確訂閱。必須使用 有效事件類型 列出的值;重複項目會被移除 |
agent_id | 整數 | null | 否 | 將傳送範圍限定至此組織內的指定智能體;省略或使用 null 則建立適用於整個組織的端點 |
回傳 201 Created,內容包括端點物件及額外的頂層 secret 欄位,其中包含原始簽署金鑰——一個 48 字元的十六進位字串:
{
"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"
}更新端點
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"]
}'| 欄位 | 類型 | 說明 |
|---|---|---|
label | 字串 | |
url | 字串 | |
events | 陣列 | |
status | 字串 | active 或 disabled。將伺服器標記為 failing 的端點設為 active,即可重新啟用 |
agent_id | 整數 | null | 設定智能體 ID 以限定端點範圍,或設為 null 使其成為機構層級端點 |
回傳 200 OK,內容為已更新的端點物件。
輪換簽署密鑰
更換端點的簽署密鑰,例如密鑰遺失或可能已洩露時。你亦可透過控制台操作:在 整合 → Webhooks 下開啟端點(機構層級及智能體端點均會 列於此處),然後選擇 輪替。
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 '{}'| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
include_copies | 布林值 | 否 | 預設為 true。亦會將新密鑰提供予你組織中其他具有相同 URL 和相同現有密鑰的端點,例如此端點在其他智能體上的複本,讓單一接收端可繼續使用同一密鑰進行驗證 |
返回 200 OK:
{
"endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
"secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
"rotated_endpoint_ids": ["c4d5e6f7-..."]
}| 欄位 | 類型 | 說明 |
|---|---|---|
endpoint | 物件 | 帶有新 secret_hint 的 端點物件 |
secret | 字串 | 新的簽署密鑰。僅於此回應中返回 |
rotated_endpoint_ids | UUID 陣列 | 現時使用新密鑰的每個端點 |
傳送測試交付
使用正常的傳送流程,向一個端點傳送合成的 webhook.test 事件,包括標準 JSON 序列化、兩個簽章標頭、傳送記錄及重試記錄。
測試會以所選端點為目標,不受其 events 篩選條件影響。
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"端點會收到如下的封裝資料:
{
"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 會返回 200 OK,即使目標端返回錯誤亦然。
檢查 success、status、response_code 及 error 以了解交付結果:
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}webhook.test 為模擬事件,無法加入端點的 events
訂閱。如首次嘗試失敗,ThunderPhone 會在約一分鐘後重試一次,
其後停止;交付將在偵錯交付下顯示
status: "failed"。測試交付不會將端點標記為 failing。
如要根據真實事件結構設定觸發條件,請傳遞可選的
event_type。交付仍為模擬交付,並包含 "sample": true;
與通話相關的範例會使用 call_id: 0 及 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 接受有效事件類型中的任何值。
省略此參數會保留通用的 webhook.test 行為。
通話完成(telephony.complete、web.complete)及 call.data_extracted
範例會在 extracted_data.fields 內載有該智能體本身需要收集資料的欄位,
並附有佔位值,與其真實通話一致。對於不收集任何資料的智能體,通話完成範例會傳送
extracted_data: null,與其真實通話一致,而 call.data_extracted
範例則會有空白的 fields(真實通話不會為此類智能體傳送該事件)。
當智能體的通話摘要已關閉時,範例的 summary 會是 null。在智能體的端點上,範例會依照該智能體產生;
在全機構端點上,可傳遞選用的 agent_id 以按某個智能體產生範例,或省略此參數以使用一般範例。
刪除端點
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"返回 204 No Content。系統會立即停止向該 URL 交付;
進行中的重試會被放棄。
偵錯交付
在判定 Webhook 未有傳送前,請檢查
GET /v1/developer/webhook-deliveries。
此項目會顯示兩個 Webhook 系統最近的嘗試,包括通話 ID、
URL 來源、HTTP 狀態、嘗試次數、允許清單內的失敗類別,以及下一次
重試時間。它不會返回事件負載、逐字稿、已儲存的錯誤文字、
回應內容或 URL 路徑。
你亦可在 智能體 → 選擇智能體 → Webhooks → 最近交付 查看相同的近期記錄。每列會顯示端點標籤,以及最近一次 嘗試所使用的 URL 來源。這是運作狀態,而非不可變更的稽核記錄:刪除端點 亦會刪除其交付記錄列。
如 n8n 出現 404,請先確認工作流程已啟用、接受 POST,並使用
正式環境 Webhook URL 而非測試 URL。401 或 403 表示可能與
驗證或簽名驗證有關;逾時表示目標延遲或可用性問題;
TLS 錯誤則表示可能與憑證鏈、主機名稱或到期日有關。