Webhook 端點

使用各端點專屬密鑰與事件篩選條件，管理多個 webhook URL。

以端點為基礎的 webhook 系統可讓你為每個組織註冊多個 目的地，每個目的地都有各自的密鑰、狀態，以及對部分事件類型的個別訂閱。這是所有新整合建議採用的模式。

請與舊版單一 URL webhook比較；此功能為向下相容而保留，但每個組織僅支援一個 URL。

端點#

端點物件#

{
  "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"
}

有效事件類型#

系統會依據以下精確集合驗證 events——清單外的值 會傳回 400。各類型的承載資料結構請參閱事件目錄。

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received（保留；尚未發送）
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated 不含智慧體內容，且僅會遞送至 全組織範圍端點。

無法明確選取 voice.ready 和 voice.failed。如要接收 這些事件，請建立一個設定 events: [] 的全組織範圍端點。空事件 清單會接收所有支援的事件，但 telephony.turn 和 web.turn 除外， 這兩者必須明確選取。

端點狀態#

• 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）絕不會傳送至該端點。你 也可以在智慧體建立工具的 Webhook 區段建立及管理這些端點。

建立端點#

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"]

請求欄位#

傳回 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"]
  }'

傳回 200 OK，包含更新後的端點物件。

輪替簽署密鑰#

更換端點的簽署密鑰，例如密鑰遺失或可能外洩時。對於限定智慧體範圍的端點，你也可以使用 控制台：開啟智慧體的 Webhook 區段，然後在端點上選擇 重新產生密鑰。組織範圍的端點需透過 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 '{}'

回傳 200 OK：

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

傳送測試傳遞#

使用一般傳送流程，將合成的 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 行為。

刪除端點#

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 路徑。

你也可以在 智慧體 → 選取智慧體 → Webhook → 最近傳遞紀錄 中查看相同的近期紀錄。各列會顯示端點標籤，以及最新 嘗試所使用的 URL 來源。這是操作狀態，而非不可變更的稽核紀錄：刪除端點 也會刪除其傳遞資料列。

若 n8n 出現 404，請先確認工作流程已啟用、接受 POST，且使用的是 正式環境 Webhook URL，而非測試 URL。401 或 403 表示可能是 驗證或簽章驗證問題；逾時表示目標端延遲或無法使用；TLS 錯誤則表示 憑證鏈、主機名稱或到期日有問題。

相關內容#