# 了解WebHook
WebHook是客户接收其发送情况的渠道。用户将邮件请求发送给 SendCloud 之后, SendCloud 会把「请求结果」同步返回给用户, 而邮件的「发送结果」和「其他事件结果」是通过 WebHook 异步返回给用户的。
# WebHook 机制
- SendCloud 为客户提供了一些邮件事件, 客户可以选择关注某些事件
- 当某事件发生, 就会触发 SendCloud 向客户设置的 URL 发送数据 ( POST )
- SendCloud推送的数据类型："Content-Type: application/x-www-form-urlencoded"
- 客户收到数据, 解析出事件和数据, 你需要在 3s 内返回HTTP Status Code 200, 否则, SendCloud 将会重发该条消息.
- WebHook解析示例, 点此下载
目前 SendCloud 支持的邮件事件如下:
| 事件 | 触发条件 |
|---|---|
| 请求(request) | 邮件请求成功 |
| 发送(deliver) | 邮件发送成功 |
| 打开(open) | 用户打开邮件 |
| 点击(click) | 用户点击链接 |
| 取消订阅(unsubscribe) | 用户取消订阅邮件 |
| 举报(report_spam) | 用户举报邮件 |
| 无效邮件(invalid) | 邮件未发送成功 |
| 软退信(soft_bounce) | 接收方拒收该邮件 |
| 转信(route) | 转信/收信路由 |
# 使用方法
- 用户自行编写 HTTP 服务, 使之能够处理相应的事件, 解析相关数据, 并开放出相应 URL
- 用户在 SendCloud 的
WebHook中选择关注的事件, 配置接收数据的 URL
# 签名验证
为了确保消息的来源身份是 SendCloud, 你可以选择对 POST 数据的来源进行安全认证. ( 不验证, 直接解析 POST 的数据也可以 ). 安全认证的方法如下:
- 通过
【发送设置】-【WebHook】获取APP KEY - 解析出 POST 数据中的
token,timestamp和signature - 使用
APP KEY,token和timestamp生成签名signature, 与 POST 数据中的signature进行校验 ( 签名算法: SHA256 (opens new window))
# 重试机制
如果遇到 URL 访问错误或超时, SendCloud 最多会重试 6 次. 每次重试的时间间隔最快为 3min, 10min, 30min, 1h, 6h, 12h, 24h. 即在消息丢失前, 你有足够的时间来修复 URL.
如果超过重试次数，SendCloud 将会把消息丢弃.
每次事件处理, 数据解析, 你需要在 3s 内返回HTTP Code 200, 否则, SendCloud 将会重发该条消息。