事件推送 Webhook
配置并验证邮件 Webhook，理解七类事件、签名、幂等和失败后的人工排查方式。
Webhook 用于把邮件事件主动推送到你的服务端，是获取每封邮件受理后结果（送达、退信、投诉、失败等）的主要途径。回调配置属于 API Key 级设置，当前由平台运营开通；客户控制台暂不提供 Webhook URL、事件订阅、签名密钥或投递日志的自助页面。
开通需要联系平台
接入 Webhook 前需联系平台运营，提供公网回调地址并确认事件订阅范围与签名模式。控制台暂不支持自助配置。
开始前的准备
提供公网 HTTPS 回调地址
回调地址必须使用 HTTPS 并具备有效证书。解析到内网、回环、链路本地或其他保留地址的域名会被拒绝。
确认事件类型与鉴权方式
与平台确认需要订阅的事件类型（见下文事件表），以及使用的签名模式：X-CALLBACK-ID 或兼容模式 X-Innomail-Signature。
保证接收接口 10 秒内返回 2xx
接收接口应在 10 秒内返回 2xx，不依赖重定向、Cookie 或自动重试。建议先持久化事件，再异步处理业务逻辑。
实现去重与对账
按 eventId 去重并持久化处理结果；按 Message ID 与控制台发送记录对账，确认最终投递状态。
可订阅事件
eventType | 含义 |
|---|---|
delivered | 收件方服务器确认接受邮件；不保证进入收件箱或已读。 |
bounced | 收到退信事件。 |
complained | 收到垃圾邮件投诉。 |
opened | 记录到打开事件；受追踪配置和客户端隐私行为影响。 |
clicked | 记录到链接点击事件。 |
delivery_delayed | 投递延迟，尚不是最终送达。 |
最后更新于