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`	字符串	是	1–120 个字符
`url`	字符串	是	HTTPS URL（仅 `localhost` / `127.0.0.1` 允许使用 `http`）
`events`	数组	否	为空或省略时订阅所有事件。必须使用有效事件类型中列出的值；重复项将被移除

返回 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`	字符串
`url`	字符串
`events`	数组
`status`	字符串	`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 概览

端点

端点对象

有效事件类型

端点状态

列出端点

创建端点

请求字段

更新端点

发送测试投递

删除端点

相关内容