---
title: "如何通过 Webhook 接收送达回执？"
description: "如何用 Webhook 接收短信和 WhatsApp 送达回执：配置接口、映射状态、事件去重、保障安全，以及补收遗漏的回执。"
canonical: "https://omnichannels.ai/zh/answers/delivery-report-webhook/"
language: "zh"
updated: "2026-10-10"
publisher: "BroadNet Technologies"
brand: "OmniChannels.ai"
---

# 如何通过 Webhook 接收送达回执？

Canonical: https://omnichannels.ai/zh/answers/delivery-report-webhook/
Language: zh
Publisher: OmniChannels.ai by BroadNet Technologies

**简短回答:** 要通过 Webhook 接收送达回执，需提供一个接受 POST 请求的 HTTPS 接口，并把其 URL 登记到消息服务商。收到事件先存储，快速返回 2xx 状态码，再异步处理。用消息 ID 匹配事件、去重，并避免迟到的状态覆盖最终状态。

## 配置接口

开发阶段可用内网穿透工具，为本地服务器生成公网 HTTPS 地址。

1. 提供一个接受 JSON 请求体 POST 请求的 HTTPS 接口。
2. 把 URL 提供给服务商，配置到正确的账户或子账户下。
3. 向自己的号码发送测试短信，并记录原始事件内容。
4. 根据真实事件映射所需字段，而不是凭假设的字段名。
5. 为所用的每个渠道保留示例数据，作为测试样本。

## 会收到哪些状态？

服务商会把运营商和渠道的回执转换为自己的状态名称。以下是 OmniChannels.ai 在短信、WhatsApp 等渠道统一使用的标准化状态。

| 状态 | 含义 | 是否为终态？ |
|---|---|---|
| SUBMITTED | 已接收并排队 | 否 |
| SENT | 已交给运营商或渠道 | 否 |
| DELIVERED | 已确认送达设备 | 通常是；之后可能出现 READ |
| READ | 已打开（仅限支持已读回执的渠道） | 是 |
| FAILED | 未送达，并尽可能附带原因 | 是 |
| REJECTED | 被拒绝，例如 Sender ID 未注册 | 是 |

## 让处理程序可靠运行

- 先存储原始内容，再返回 2xx。如果存储失败，返回 5xx 以便事件被重试。
- 把实际处理放到队列或工作进程中，而不是在响应之前完成。
- 按消息 ID 去重；同一状态可能到达两次。
- 为状态设定优先级，避免迟到的 SENT 覆盖 DELIVERED。
- 遇到无法识别的状态值时照常接收，不要报错。
- 切勿在 Webhook 处理程序内部重发短信。

## 保障安全并补收遗漏的回执

只接受 HTTPS,使用足够长且难以猜测的路径，校验请求体结构，并在退款等不可逆操作前先通过状态查询接口确认状态。如果您的接口曾经宕机，可请服务商重新推送该时段的回执，或从其报表接口读取状态。

在 SMPP 方式下，回执通过绑定以 deliver_sm 的形式到达，而不是 Webhook。部分运营商回执延迟甚至不返回，因此应将其视为有力证据，而非已读的证明。

## 官方来源

- [SMPP Protocol Specification v3.4 (Issue 1.2) — SMPP.org](https://smpp.org/SMPP_v3_4_Issue1_2.pdf)
- [RFC 9110: HTTP Semantics (IETF)](https://datatracker.ietf.org/doc/html/rfc9110)

## 相关问题

- https://omnichannels.ai/zh/answers/sms-delivery-report-statuses/
- https://omnichannels.ai/zh/answers/integrate-sms-api/
- https://omnichannels.ai/zh/answers/connect-sms-provider-smpp/
- https://omnichannels.ai/zh/answers/why-sms-not-delivered/

更新于: 2026-10-10