简短回答
要通过 Webhook 接收送达回执，需提供一个接受 POST 请求的 HTTPS 接口，并把其 URL 登记到消息服务商。收到事件先存储，快速返回 2xx 状态码，再异步处理。用消息 ID 匹配事件、去重，并避免迟到的状态覆盖最终状态。
配置接口
开发阶段可用内网穿透工具，为本地服务器生成公网 HTTPS 地址。
- 提供一个接受 JSON 请求体 POST 请求的 HTTPS 接口。
- 把 URL 提供给服务商，配置到正确的账户或子账户下。
- 向自己的号码发送测试短信，并记录原始事件内容。
- 根据真实事件映射所需字段，而不是凭假设的字段名。
- 为所用的每个渠道保留示例数据，作为测试样本。
会收到哪些状态？
服务商会把运营商和渠道的回执转换为自己的状态名称。以下是 OmniChannels.ai 在短信、WhatsApp 等渠道统一使用的标准化状态。
| 状态 | 含义 | 是否为终态？ |
|---|---|---|
| SUBMITTED | 已接收并排队 | 否 |
| SENT | 已交给运营商或渠道 | 否 |
| DELIVERED | 已确认送达设备 | 通常是；之后可能出现 READ |
| READ | 已打开（仅限支持已读回执的渠道） | 是 |
| FAILED | 未送达，并尽可能附带原因 | 是 |
| REJECTED | 被拒绝，例如 Sender ID 未注册 | 是 |
让处理程序可靠运行
- 先存储原始内容，再返回 2xx。如果存储失败，返回 5xx 以便事件被重试。
- 把实际处理放到队列或工作进程中，而不是在响应之前完成。
- 按消息 ID 去重；同一状态可能到达两次。
- 为状态设定优先级，避免迟到的 SENT 覆盖 DELIVERED。
- 遇到无法识别的状态值时照常接收，不要报错。
- 切勿在 Webhook 处理程序内部重发短信。
保障安全并补收遗漏的回执
只接受 HTTPS,使用足够长且难以猜测的路径，校验请求体结构，并在退款等不可逆操作前先通过状态查询接口确认状态。如果您的接口曾经宕机，可请服务商重新推送该时段的回执，或从其报表接口读取状态。
在 SMPP 方式下，回执通过绑定以 deliver_sm 的形式到达，而不是 Webhook。部分运营商回执延迟甚至不返回，因此应将其视为有力证据，而非已读的证明。