Skip to main content
ThunderPhone 会在通话期间发生事件时向您的服务器发送 HTTP POST 请求——例如入站通话开始、通话结束、评分运行完成、触发告警等。共有两种投递模式

Webhook 端点(推荐)

支持多个 URL、每个端点独立的密钥、每个端点独立的事件筛选,以及自动重试。 通过 GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints 管理。

单 URL 旧版 Webhook

每个组织一个 URL。承载通话生命周期事件,包括阻塞式配置交换。通过 GET/PUT /v1/webhook 管理。
事件目录中的全部十种事件类型都会通过 Webhook 端点投递。六种通话生命周期事件 (telephony.incomingtelephony.completetelephony.toolweb.incomingweb.completeweb.tool)也会发送到旧版单 URL Webhook——如果您同时配置了旧版 URL 和匹配的端点,您会在两个路径上收到该事件。阻塞行为(telephony.incoming / web.incoming 配置交换以及 Webhook 模式的工具分派)仅存在于旧版路径;每次端点投递都是即发即忘的通知。

载荷格式

端点投递的数据是一个包含 dataevent_idtype 的 JSON 对象:
event_id 对于每个已发出的事件都是唯一的。它在重试期间以及接收该事件的每个端点之间保持一致——请基于它进行去重。 旧版单 URL Webhook 会发送相同的 typedata,但不包含 event_id
在线路上传输时,每个请求体都会以规范形式序列化——键按字母顺序排序、无空白字符、使用 UTF-8。这些文档中的格式化示例仅用于提高可读性。 请参阅事件目录,获取事件类型和载荷字段的完整列表。

签名验证

每个请求都会在 X-ThunderPhone-Signature 标头中携带针对原始请求 正文的 HMAC-SHA256 签名。签名密钥是端点的 secret(对于旧版 投递,则为组织级 webhook 的 secret)。

步骤

  1. 在进行任何解析之前读取原始请求正文。
  2. 计算 hmac_sha256(secret, body).hexdigest()
  3. 使用恒定时间比较结果与 X-ThunderPhone-Signature 标头。
我们对传输的确切字节进行签名,这些字节采用规范 JSON 序列化格式(键已排序,分隔符紧凑)。因此,针对原始正文进行验证始终有效——如果您的框架仅提供已解析的 JSON,使用已排序的键和紧凑分隔符重新序列化即可生成完全相同的字节。两种方法均在验证指南中介绍。

投递语义

这些语义适用于投递到端点的事件。旧版单 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 秒。
出站 webhook 来自 ThunderPhone 的云 IP 范围。 如果您的防火墙需要允许列表,请联系支持团队,我们将 提供当前的 IP 范围。

在旧版 webhook 与基于端点的 webhook 之间选择

新集成应通过基于端点的 webhook 使用事件。仅当您需要在接听时 动态配置通话,或使用 webhook 模式工具调度时,才保留(或添加)旧版 URL——这些 请求/响应交换仅在旧版路径上运行。

相关内容

事件目录

所有事件类型及其载荷。

Webhook 端点

管理多个端点、事件筛选器和密钥。

telephony.incoming / web.incoming

您的服务器必须响应以配置通话的阻塞请求。

telephony.complete / web.complete

包含转录文本、录音和指标的通话后载荷。