Sign inGet Started

SMS 回调 URL

回调 URL 代替您的 webhook 端点,接收单条 SMS 消息的事件,或某个消息配置文件下所有消息的事件。当某条消息或某个项目需要独立的接收端时,请使用回调 URL。

你可以在控制台中管理签名密钥、尝试记录和重放,也可以通过 API 和 bird webhooks callbacks 命令进行管理。在创建消息配置文件或更新消息配置文件时设置其 URL。

选择事件的发送目标

URL 在消息被接受时解析一次,并在该消息的整个生命周期内沿用。之后修改配置文件不会改变正在传输的消息的路由。

消息使用的 URL
发送时设置了 options.callback_url该 URL
发送时将 options.callback_url 设为 null无:事件发送到你的 webhook 端点
未设置该字段,通过消息配置文件发送该配置文件的 options.callback_url
由消息配置文件中的号码接收该配置文件的 inbound.callback_url,其次是其 options.callback_url
以上各项均未提供 URL无:事件发送到你的 webhook 端点

URL 必须是 HTTPS,长度不超过 2048 个字符,且必须是公网地址。如果主机是私有地址、环回地址或链路本地地址,则返回 422。

回调尝试列表会显示接收消息的事件投递到了哪里。

URL 替代了什么

当某条消息适用 URL 时,该消息的事件不会发送到你的 webhook 端点。工作区中的其他消息仍会发送到这些端点。回调失败时,事件不会改为发送到你的端点:请使用重放来恢复。

MCP Events 订阅和连接器端点仍会收到该消息的事件。

消息配置文件的 callback_events 用于从 sms.accepted、sms.sent、sms.delivered、sms.undelivered、sms.failed、sms.rejected 和 sms.expired 中选择哪些出站事件发送到该 URL。列表中未包含的事件,也不会发送到该消息的任何 webhook 端点。未设置列表的配置文件,以及未使用配置文件的发送,会投递所有出站事件。sms.received 从不被过滤。载荷格式见 SMS 事件。

验证签名

回调使用与 webhook 端点相同的 Standard Webhooks 头和 HMAC-SHA256 签名,因此现有的验证代码无需修改即可使用。密钥是你工作区的回调签名密钥。所有回调 URL 和所有语音序列 webhook 请求共用这一个密钥,因此一次轮换会同时作用于两者。

第一个密钥从不显示。请在控制台的 Webhooks → Direct callbacks 下,或通过轮换回调签名密钥进行轮换,以获得一个可用的密钥。新密钥只显示一次,因此请在离开页面前保存。在接下来的 24 小时内,每个回调都会同时用旧密钥和新密钥签名,因此你可以部署新密钥而不会丢失投递。一个工作区最多同时持有 5 个有效密钥,因此在重叠期内再次轮换可能会被拒绝。轮换会在大约一分钟内生效。

在依赖签名验证之前,请先轮换密钥:在轮换之前,回调携带的签名使用的是你无法读取的密钥。

重试与重复

回调遵循 webhook 端点的重试计划:在约 27.5 小时内进行八次尝试,15 秒内返回 2xx 即视为成功。与端点不同,回调 URL 永远不会被暂停。

投递至少进行一次,且不保证顺序。请根据 webhook-id 头去重,并按载荷中的 timestamp 排序。

查找并重放失败的回调

控制台中 Webhooks 下的 Direct callbacks 标签页和列出回调投递尝试会按从新到旧的顺序显示工作区的回调尝试,包括 URL、你的接收端返回的状态和延迟。尝试记录保留三天。

重放失败的回调投递会为在你选择的时间窗口内回调失败的每个事件再排队一次尝试,与重放端点投递对端点的处理方式相同。如果某个事件在该时间窗口内也已成功投递,则会被跳过。窗口外的成功投递不计入,因此该事件会被再次发送。单次重放最多发送窗口内最早的 10,000 个失败事件;如果中断时间较长,请将开始时间设得更晚并再次重放,以处理剩余事件。

重放会发送到失败尝试上记录的 URL,而不是你的 webhook 端点,也不是配置文件当前的 URL。它用于在你的接收端中断后进行恢复。对于发送到错误 URL 的消息,重放无法恢复,请重新发送该消息。重放与端点重放共用同一个每日上限。

后续步骤