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 URL（仅 `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 投递；正在进行的重试将被放弃。