---
title: "SMS 回调 URL"
description: "将 SMS 消息的事件或消息配置文件收到的回复发送到你自己的 HTTPS URL。内容涵盖路由、签名校验、重试以及失败回调的重放。"
canonical: "https://bird.com/zh-sg/wendang/guides/sms/callbacks"
---

# SMS 回调 URL

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

你可以在控制台中管理签名密钥、尝试记录和重放，也可以通过 [API](/docs/api/reference/rotate-webhook-callback-signing-secret) 和 `bird webhooks callbacks` 命令进行管理。在[创建消息配置文件](/docs/api/reference/create-sms-messaging-profile)或[更新消息配置文件](/docs/api/reference/update-sms-messaging-profile)时设置其 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 事件](/docs/guides/sms/events)。

## 验证签名

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

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

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

## 重试与重复

回调遵循 [webhook 端点的重试计划](/docs/guides/webhooks#delivery-semantics)：在约 27.5 小时内进行八次尝试，15 秒内返回 `2xx` 即视为成功。与端点不同，回调 URL 永远不会被暂停。

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

## 查找并重放失败的回调

控制台中 **Webhooks** 下的 **Direct callbacks** 标签页和[列出回调投递尝试](/docs/api/reference/list-webhook-callback-attempts)会按从新到旧的顺序显示工作区的回调尝试，包括 URL、你的接收端返回的状态和延迟。尝试记录保留三天。

[重放失败的回调投递](/docs/api/reference/create-webhook-callback-replay)会为在你选择的时间窗口内回调失败的每个事件再排队一次尝试，与[重放端点投递](/docs/guides/webhooks#replaying-failed-deliveries)对端点的处理方式相同。如果某个事件在该时间窗口内也已成功投递，则会被跳过。窗口外的成功投递不计入，因此该事件会被再次发送。单次重放最多发送窗口内最早的 10,000 个失败事件；如果中断时间较长，请将开始时间设得更晚并再次重放，以处理剩余事件。

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

## 后续步骤

- [SMS 事件](/docs/guides/sms/events)：每个事件的载荷
- [Webhook 与事件](/docs/guides/webhooks)：签名、重试和重放的完整说明
- [发送 SMS](/docs/guides/sms/sending-sms)：发送请求

## Related resources

- [Sending your first SMS](/learn/sms/sending-your-first-sms) (video)
- [What does SMS mean?](/explained/sms/what-does-sms-mean) (answer)
- [SMS](/sms-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=sms)
