POST 请求——例如入站通话开始、通话结束、评分运行完成、触发告警等。共有两种投递模式:
Webhook 端点(推荐)
支持多个 URL、每个端点独立的密钥、每个端点独立的事件筛选,以及自动重试。
通过
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints 管理。单 URL 旧版 Webhook
每个组织一个 URL。承载通话生命周期事件,包括阻塞式配置交换。通过
GET/PUT /v1/webhook 管理。telephony.incoming、telephony.complete、telephony.tool、
web.incoming、web.complete、web.tool)也会发送到旧版单 URL Webhook——如果您同时配置了旧版 URL 和匹配的端点,您会在两个路径上收到该事件。阻塞行为(telephony.incoming / web.incoming 配置交换以及 Webhook 模式的工具分派)仅存在于旧版路径;每次端点投递都是即发即忘的通知。
载荷格式
端点投递的数据是一个包含data、event_id 和 type 的 JSON 对象:
event_id 对于每个已发出的事件都是唯一的。它在重试期间以及接收该事件的每个端点之间保持一致——请基于它进行去重。
旧版单 URL Webhook 会发送相同的 type 和 data,但不包含 event_id:
签名验证
每个请求都会在X-ThunderPhone-Signature 标头中携带针对原始请求
正文的 HMAC-SHA256 签名。签名密钥是端点的 secret(对于旧版
投递,则为组织级 webhook 的 secret)。
步骤
- 在进行任何解析之前读取原始请求正文。
- 计算
hmac_sha256(secret, body).hexdigest()。 - 使用恒定时间比较结果与
X-ThunderPhone-Signature标头。
投递语义
这些语义适用于投递到端点的事件。旧版单 URL webhook 仅进行一次同步尝试,不会重试。重试
重试
每个事件会立即尝试投递一次。任何
2xx 响应
都会确认投递。出现任何其他结果(非 2xx、
连接错误、超时)时,我们会在首次尝试后的 1 分钟、5 分钟、30 分钟、2 小时、6 小时、
12 小时和 24 小时进行重试——共 8 次尝试,覆盖
24 小时。如果所有尝试均失败,投递将停止,端点
会在webhook 端点中被标记为
status="failing"。一旦持久化接受载荷,请尽快返回 2xx;
请异步处理。顺序
顺序
投递顺序尽力保证。实际上,我们会按照事件发出的
顺序进行投递,但重试可能会在失败后改变顺序。
始终根据
call_id / 对象 id 进行去重和协调。重复
重复
投递采用至少一次语义:在我们未收到响应后进行的重试
可能会重复投递事件。每次重试都会携带相同的
event_id,因此请存储已处理的 id 并跳过重复项。event_id
也会在端点之间共享——订阅同一事件的两个端点会收到相同的
event_id。超时
超时
每次端点投递的超时时间为 30 秒。在旧版路径上,会影响实时通话行为的
阻塞请求——
telephony.incoming / web.incoming
配置交换——会在 10 秒后超时,但较慢的响应会延迟接听通话,
因此请尽量在数秒内响应。Webhook 模式的工具调度允许 20 秒。源 IP
源 IP
出站 webhook 来自 ThunderPhone 的云 IP 范围。
如果您的防火墙需要允许列表,请联系支持团队,我们将
提供当前的 IP 范围。
在旧版 webhook 与基于端点的 webhook 之间选择
新集成应通过基于端点的 webhook 使用事件。仅当您需要在接听时
动态配置通话,或使用 webhook 模式工具调度时,才保留(或添加)旧版 URL——这些
请求/响应交换仅在旧版路径上运行。
相关内容
事件目录
所有事件类型及其载荷。
Webhook 端点
管理多个端点、事件筛选器和密钥。
telephony.incoming / web.incoming
您的服务器必须响应以配置通话的阻塞请求。
telephony.complete / web.complete
包含转录文本、录音和指标的通话后载荷。