Webhook 端點

基於端點的 webhook 系統讓你可為每個組織登記多個 目的地，每個目的地均可擁有獨立的密鑰、狀態，以及訂閱的部分 事件類型。這是所有新整合建議採用的模式。

可與舊版單一 URL webhook比較， 後者為向後兼容而保留，但每個組織只支援一個 URL。

端點

端點物件

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

有效事件類型

events 會按照以下精確集合驗證——不在清單內的值 會回傳 400。請參閱事件目錄以了解各類型的 payload 格式。

• telephony.incoming, telephony.complete, telephony.tool
• web.incoming, web.complete, web.tool
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

端點狀態

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

回傳一個端點物件陣列。

建立端點

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 訂閱。如首次嘗試失敗，傳遞會按照一般事件傳遞相同的重試排程進行。

刪除端點

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

回傳 204 No Content。系統會立即停止傳送至該 URL； 進行中的重試將會中止。

相關內容