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}/test`	`admin+`	傳送已簽署的測試傳遞

端點物件

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

欄位	類型	說明
`id`	UUID	端點 ID
`label`	string	顯示名稱，1–120 個字元
`url`	string	HTTPS URL；開發環境可使用 `http://localhost`
`events`	string 陣列	訂閱的事件類型（請參閱有效值）。空陣列會訂閱所有事件，但明確限定的逐輪事件（`telephony.turn`／`web.turn`）除外
`status`	string	`active`、`disabled`（手動暫停）或 `failing`（當一次傳遞在 24 小時重試排程中耗盡所有嘗試且未取得任何 2xx 時自動設定）
`secret_hint`	string	簽署密鑰的前 4 個與後 4 個字元，中間以省略號表示（`a1b2…9f0e`）——足以比對你在本機儲存的密鑰，同時不會暴露完整值
`created_at`、`updated_at`	timestamp

有效事件類型

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

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

端點狀態

active——傳遞正常進行。
disabled——透過 PATCH 手動暫停。不會傳送任何請求。我們絕不會變更 disabled 端點的狀態；是否將其恢復為 active，一律由你決定。
failing——當傳遞至端點的請求耗盡完整重試排程（24 小時內嘗試 8 次），且始終未取得 2xx 時自動設定。失敗中的端點不會再接收任何流量。修正端點後，透過 PATCH 將其狀態改回 active；尚未耗盡重試排程的傳遞會從中斷處繼續。

列出端點

cURL

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

回傳一個端點物件陣列。

建立端點

cURL

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

Python

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 網址（僅 `localhost` / `127.0.0.1` 可使用 `http`）
`events`	陣列	否	空白或省略時，會訂閱除 `telephony.turn` / `web.turn` 以外的所有事件；這兩種事件必須明確訂閱。必須使用有效事件類型中列出的值；重複項目會被移除

回傳 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

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`，即可重新啟用

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

傳送測試傳遞

使用一般傳遞管線向單一端點傳送合成的 webhook.test 事件，其中包括標準 JSON 序列化、 X-ThunderPhone-Signature、傳遞記錄與重試追蹤。無論選取端點的 events 篩選條件為何，測試都會以該端點為目標。

cURL

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

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

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