接收客户回调
在客户配置中启用公网 HTTP 回调地址与事件。处理器验证签名并持久化事件后，再推进业务逻辑。
回调请求头
| Header | 说明 |
|---|---|
| X-Webhook-Event | 事件类型，例如 status_report |
| X-Webhook-Timestamp | 毫秒时间戳 |
| X-Webhook-Sign | md5(timestamp + raw_body + secret) |
| Content-Type | application/json |
验签核心示例
Python
import hashlib
import hmac
# raw_body 是未经解析、未经重新序列化的 UTF-8 原始正文
expected = hashlib.md5(
(timestamp + raw_body + secret).encode("utf-8")
).hexdigest()
valid = hmac.compare_digest(expected, received_sign.lower())
# 同时校验时间戳、事件类型与业务归属状态报告中的关联字段
| 字段 | 含义 |
|---|---|
| task_no / client_request_id | 关联发送任务与客户业务 |
| dispatch_no | 号码明细编号 |
| status / receipt_status / receipt_result | 明细状态与回执结果 |
| receipt_version / receipt_event_no | 回执版本和事件关联 |
| is_correction | 标识后续纠正 |
| billing_status | 相关账务状态，不等于回执状态 |
响应、重试与幂等
有效处理后返回 2xx。网络或非成功响应可能引起重试，重复事件需要幂等处理。后续纠正应结合 receipt_version 判断，不让旧事件覆盖新状态。
订阅与能力范围
当前事件与字段以实际客户配置为准。上行和其他投递可通过相应配置接入；不要仅根据历史文档假定已开通所有事件。