如何设置 SMS 交付状态回调

选择正确的回调用例

从一个问题开始：回调应该在您的业务中改变什么？对于订单提醒、一次性密码（OTP）交付监控或客户通知，答案通常是不同的。商店可能在发送收据之前关心“已交付”状态。银行可能在30秒内关心“失败”，因为一个从未到达的登录代码会直接产生支持成本。

这个选择在您调整任何设置之前很重要。如果您正在记录如何设置短信交付状态回调，请先选择一个工作流程，并用简单的词语命名结果：确认交付、发现失败或跟踪延迟。一个回调可以在后面支持这三者，但第一个版本应该回答一个实际问题。

保持范围狭窄。运输团队可能只需要链条中最后一条短信的状态更新，而不是每个提醒。密码重置流程可能只在消息被接受或拒绝时需要回调，因为“等待”对已经盯着登录屏幕的用户来说并不是一个有用的状态。

确认您的短信提供商的回调模型

提供商并不都使用相同的语言。有些使用交付回执，有些使用网络钩子，还有一些暴露您必须轮询的状态URL。阅读提供商文档以获取确切的事件名称，并检查哪些状态可用。

一个提供商可能只发送最终状态。另一个可能为一条消息发送多个更新，这会改变您稍后存储数据的方式。如果提供商同时支持消息级和账户级回调，请选择与您上面选择的工作流程匹配的那个。这个细节可以避免在第一次测试到来时的困惑，因为您的应用会看到一条短信的两个事件。

这里有一个小陷阱。文档通常显示一个JSON示例，然后真实账户返回一个稍微不同形状的不同产品层级。比较API注释、仪表板标签和任何示例有效负载，然后再连接端点。如果您的提供商提供了交付回执的单独文档，也请阅读那个。

对于已经处理其他基于事件的系统的团队来说，这种模式会很熟悉。逻辑类似于事务性电子邮件的电子邮件网络钩子事件：您需要知道存在哪些事件，哪些事件您关心，以及哪些事件绝不应该触发面向客户的逻辑。

准备您的公共回调端点

您的回调端点需要一个公共的 HTTPS URL。不是本地端口。不是私有 IP。提供者必须能够从您的网络外部访问它，并且大多数 SMS 平台在生产环境中会拒绝普通的 HTTP。一个常见的结构是 /webhooks/sms/status，因为当日志和仪表板填满时，它仍然可读。

保持路由稳定。如果您每周重命名一次，您的仪表板设置将落后于您的代码。对于第一个版本，使用一个路径、一个方法和一个处理程序。POST 是通常的选择。

接受传入请求而不在慢工作上阻塞。端点应该读取请求，验证基本信息，并快速响应。重处理应放在作业队列或后台任务中。这样一来，一次突发的回调不会长时间保持连接打开，从而导致重试。

在连接提供者之前，先用简单的请求体测试路由。一个虚拟 POST 的 200 响应比后期的长时间调试会话更有意义。如果您已经熟悉其他渠道的回调设计，那么相同的原则也适用于网络推送通知最佳实践，特别是在响应时机和端点清晰度方面。

定义您的应用所需的事件有效负载

不要仅仅因为提供者发送了每个字段就存储它们。首先将回调映射到您的内部模型中。至少，大多数团队需要消息 ID、接收者、状态、时间戳和错误代码字段。一些提供者还包括运营商数据、国家或网关引用，这些在支持工作中会有所帮助。

保持您的映射严格。如果提供者称一个字段为 sms_id，而您的数据库使用 provider_message_id，请只写一次翻译并重用它。这可以防止在第二个集成到来时出现“在暂存环境中有效”的问题。回调有效负载应该更新一个 SMS 记录，而不是创建神秘的重复项。

考虑状态历史，而不仅仅是最新状态。单个消息可以从已接受转变为已发送再到已送达，或从排队转变为失败。如果您过早地将这些合并为一个文本字段，您将失去解释代码为何迟到的线索。当客户说“我从未收到过”时，这条线索很重要，支持需要的不仅仅是耸耸肩。

对于已经在电子邮件中管理发件人身份和消息信任的团队，类似的字段规范也出现在DKIM SPF DMARC 设置用于事务性和其他身份验证工作。数据模型不同，但习惯是相同的：捕获证明发生了什么的字段。

在您的 SMS 设置中注册回调

大多数提供者允许您在仪表板屏幕中或通过 API 设置输入回调 URL。有些需要先进行账户级别的设置，然后再进行消息级别的覆盖。查找诸如交付回调、状态回调、Webhook URL 或收据 URL 的标签。措辞可能有所不同，但目标是相同的。

当仪表板要求时，请使用提供者的确切字段名称。交付事件的 URL 可能与入站回复的 URL 分开。如果您将两者混合，您的应用可能会收到无法解释的数据。这是一个简单的错误，而且常见到足以成为检查清单的一项。

权限在这里可能很重要。可能需要仅限管理员的账户来更改回调设置，或者 API 密钥可能需要写入范围。如果仪表板在保存之前要求验证，请在发布代码之前完成该步骤。否则，回调可能看起来“已配置”，而没有请求到达您的端点。

一旦设置被保存，从您在生产中使用的同一账户或租户发送一条消息。在错误的工作区配置的回调是一个无聊的失败，这在某种意义上是好的，因为无聊的失败比静默的失败更容易修复。

确保并验证传入请求

默认情况下永远不要信任请求体。根据您的提供者支持的内容，检查共享密钥令牌、签名头、IP 白名单或签名时间戳。这些方法中的任何一种单独使用可能就足够，但许多团队结合两种检查以获得更好的控制。

签名验证应在任何数据库写入之前进行。如果签名失败，拒绝请求并记录尝试。如果提供者包含时间戳，请将其与您的服务器时钟进行比较，以降低重放风险。昨天发送的回调今天不应被接受，仅仅因为格式看起来仍然有效。

IP 白名单听起来简单，直到提供者更改基础设施。仅在提供者发布固定范围并保持更新时使用它。秘密令牌通常更易于维护，签名验证比单独的静态令牌更强。顺便说一句：如果您的安全团队要求三者兼而有之，他们并不是在夸大其词。

不要忘记传输保护。HTTPS 是基础。证书必须有效，如果提供者不遵循重定向，则应避免重定向。这是一个在第一个恶意行为者尝试向您的系统发布虚假交付更新之前感觉无聊的步骤。

在您的系统中存储交付更新

使用提供者的消息 ID 和您自己的内部 ID 将每个回调与原始 SMS 记录关联。这个链接是每个后续报告的关键。没有它，您最终会通过电话号码搜索日志，一旦多个活动使用相同的收件人，这会变得很麻烦。

按顺序写状态变化。如果提供者发送了排队、然后发送、然后交付，保持这个顺序。如果一个较旧的回调迟到到达，忽略它或在保存之前与最新已知状态进行比较。延迟的“已发送”更新不应覆盖较新的“已交付”状态。

如果可以，使用提供者时间和本地接收时间的时间戳。第一个有助于外部追踪。第二个在您的服务器缓慢或短暂不可用时有助于事件响应。这个组合为您提供足够的细节，以便在没有猜测的情况下回答支持票。

一个简单的表格可以帮助团队就状态处理达成一致：

也要考虑下游报告。如果您的客户成功团队想查看按活动划分的交付率，请在消息旁边存储活动 ID。如果财务部门想要对账 OTP 量，请保留模板名称。小字段可以节省长时间的会议。

设置警报和后备处理

回调以可预测的方式失败：端点返回 500，签名检查开始拒绝所有内容，或者提供者停止为特定帐户发送请求。对每种情况设置一个警报。如果在合理的时间窗口内没有回调到达某条消息，那就是一个值得发出警报或至少发送电子邮件的信号。

为“回调停止”设置一个警报，为“验证失败”设置另一个警报，为“收到错误状态”设置第三个警报。这三者是不同的问题。缺失的回调可能意味着网络问题。失败的状态可能意味着运营商拒绝了 SMS。验证失败可能意味着您的密钥已轮换且提供者未更新。

有一个后备路径。如果提供者支持轮询，当回调缺失或延迟时使用它。轮询不应该是你的首选，但比盲点要好。一些团队仅对高价值消息进行轮询，例如 OTP 或支付确认，这样可以控制额外的流量。

如果你的团队已经在其他渠道监控可送达性信号，类似的习惯也适用于电子邮件退信处理最佳实践。渠道不同，但操作响应相同：监控错误状态，干净地记录它们，并决定何时重试、警报或停止。

在一个地方记录后备规则，并让支持团队阅读。客户不应该猜测失败的 SMS 是否会自动重试。如果答案是“对于 OTP 不会”，就明确说明。如果答案是“10分钟后轮询”，就写下确切的数字并在所有地方使用。