Webhook 会在送达事件发生时将其推送到你的服务器:message.sent、message.delivered、message.failed。它们是让你自己的数据库与每条消息保持同步的最省成本的方式,而它们失败的原因往往很平常:一次部署、一张过期证书、一条防火墙规则,或一个变慢的处理程序。本文介绍失败时会发生什么,以及如何干净利落地恢复。
投递为何失败
如果你的端点没有在 5 秒 内以 2xx 状态响应,这次尝试就算失败。实际原因通常包括:
- 部署或重启导致端点停机几分钟。
- TLS 证书过期或配置错误。
- 防火墙或 WAF 规则开始拦截我们的请求。
- 处理程序在响应前先执行实际工作,在高负载下耗时超过超时时限。
重试计划
失败的尝试会重试 24 小时内重试 6 次,间隔逐渐加长:第一次失败后 1 分钟,然后是 5 分钟、30 分钟、2 小时和 12 小时。这足以覆盖一次部署、一次重启,以及大多数持续一个下午的故障。最后一次尝试之后,该事件会被标记为未送达。
未送达事件与重放
控制面板中的每个端点都有一个未送达事件列表,保留 30 天,并附有最后一次尝试的状态码或错误。端点修复后,可以逐个重放事件,也可以批量选择后重放。重放的事件沿用原始事件 ID,但会获得新的时间戳和签名,因此按事件 ID 去重的处理程序只会处理一次,即使之前某次尝试实际上已经送达你那里。
端点健康状况
同一页面会显示每个端点的成功率、最近一次失败和平均响应时间。如果处理程序需要四秒才能响应,在它开始超时之前,你就能在这里看到。
经得起这一切的处理程序
- 先验证。检查
X-Meteor-Signature标头中的 HMAC-SHA256 签名是否与原始请求体及X-Meteor-Timestamp标头相符,并拒绝过旧的时间戳。签名证明事件来自我们;时间戳则可防止其他任何人重放事件。 - 快速确认。保存事件并立即返回 200;实际工作放到后台任务中完成。
- 去重。保存已处理过的事件 ID,忽略重复事件。重试和重放是正常现象,不是错误。
- 按时间而不是到达顺序排序。重放的
message.sent可能晚于同一条消息的message.delivered到达。请按created_at和状态优先级排序,并且绝不要把消息从已送达改回已发送。 - 监控。针对你自己的错误率设置告警,并在每次事故后检查未送达列表。
生产环境 Webhook 指南为每个步骤都提供了代码。
测试失败路径
使用测试密钥时,Webhook 的触发方式与真实环境完全相同,同样带有签名,但不会实际发送任何消息。可以用它检查处理程序能否验证签名、能否应对重复事件,以及能否保持状态顺序。然后在发送测试消息期间将端点停止几分钟,再让它恢复:重试应当补送错过的事件,你的数据库最终也应处于正确状态。从未送达列表发起的重放行为相同,并沿用原始事件 ID。


