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",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

有效事件類型#

events 會根據以下確切集合驗證——清單以外的值會 傳回 400。請參閱事件目錄，了解每種類型的 payload 格式。

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• call.graded, call.data_extracted
• 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，絕不會傳送至該端點。你 亦可在智能體建立工具的 Webhooks 區段建立及管理這些端點。

建立端點#

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.test 事件，包括標準 JSON 序列化、 X-ThunderPhone-Signature、遞送記錄及重試追蹤。 無論所選端點的 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 訂閱。如首次嘗試失敗，遞送會遵循與一般事件遞送相同的重試時間表。

如要針對真實事件結構設定觸發條件，請傳入可選的 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 路徑。

你亦可在 智能體 → 選擇智能體 → Webhooks → 最近遞送 中查看相同的最近記錄。每列會顯示端點標籤，以及最新一次 嘗試所使用的 URL 來源。這是營運狀態，而非不可變更的稽核記錄：刪除端點 亦會刪除其遞送記錄列。

如 n8n 出現 404，請先確認工作流程已啟用、接受 POST，並使用 正式 Webhook URL 而非測試 URL。401 或 403 表示 驗證或簽名驗證出現問題；逾時表示目標位置的延遲 或可用性問題；TLS 錯誤則表示憑證鏈、主機名稱或到期日出現問題。

相關內容#