Webhook 端點

以端點為基礎的 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 陣列	訂閱的事件類型（請參閱有效值）。空陣列會訂閱所有事件
`status`	string	`active`、`disabled`（手動暫停）或 `failing`（當傳遞在 24 小時的重試排程中用盡所有嘗試次數，且未取得任何單一 2xx 回應時自動設定）
`secret_hint`	string	簽署密鑰的前 4 個與後 4 個字元，並以省略號表示（`a1b2…9f0e`）——足以讓你與本機儲存的密鑰交叉比對，同時不會揭露完整值
`created_at`, `updated_at`	timestamp

端點的完整 secret 僅會在建立時傳回一次，此後不會再傳回。請安全儲存——若遺失密鑰，請刪除端點並重新建立。

有效事件類型

events 會依照此精確集合進行驗證——清單外的值會傳回 400。請參閱事件目錄以瞭解各類型的酬載格式。

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

請求欄位

欄位	類型	必填	說明
`label`	string	是	1–120 個字元
`url`	string	是	HTTPS URL（僅 `localhost` / `127.0.0.1` 允許使用 `http`）
`events`	array	否	留空或省略即訂閱所有事件。必須使用有效事件類型中列出的值；重複項目會被移除

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

secret僅會在建立時回傳。後續的 GET 回應只會包含 secret_hint。在關閉回應前，請將完整值複製到你的密鑰管理工具。

更新端點

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`	string
`url`	string
`events`	array
`status`	string	`active` 或 `disabled`。將伺服器標記為 `failing` 的端點設為 `active`，即可重新啟用

回傳 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；捨棄進行中的重試。

事件目錄

你可以訂閱的完整 events 值清單。

Webhook 概覽

簽章驗證與傳送語意。

Webhooks

Function Tools

端點

端點物件

有效事件類型

端點狀態

列出端點

建立端點

請求欄位

更新端點

傳送測試傳遞

刪除端點

相關內容

事件目錄

Webhook 概覽

​端點

​端點物件

​有效事件類型

​端點狀態

​列出端點

​建立端點

​請求欄位

​更新端點

​傳送測試傳遞

​刪除端點

​相關內容

事件目錄

Webhook 概覽

端點

端點物件

有效事件類型

端點狀態

列出端點

建立端點

請求欄位

更新端點

傳送測試傳遞

刪除端點

相關內容