• 覆盖 228 个目的地
  • 始终无需 KYC
  • 支持 Bitcoin、Monero、USDT 等 7 种币种

产品阅读约 3 分钟

Webhook 失败与重放:实用指南

Webhook 投递为何失败、24 小时内的重试如何运作,以及如何逐个或批量重放未送达事件而不重复处理。

SMSMeteor 产品团队发布于 2026年9月21日,更新于

Webhook 会在送达事件发生时将其推送到你的服务器:message.sent、message.delivered、message.failed。它们是让你自己的数据库与每条消息保持同步的最省成本的方式,而它们失败的原因往往很平常:一次部署、一张过期证书、一条防火墙规则,或一个变慢的处理程序。本文介绍失败时会发生什么,以及如何干净利落地恢复。

投递为何失败

如果你的端点没有在 5 秒 内以 2xx 状态响应,这次尝试就算失败。实际原因通常包括:

  • 部署或重启导致端点停机几分钟。
  • TLS 证书过期或配置错误。
  • 防火墙或 WAF 规则开始拦截我们的请求。
  • 处理程序在响应前先执行实际工作,在高负载下耗时超过超时时限。

重试计划

失败的尝试会重试 24 小时内重试 6 次,间隔逐渐加长:第一次失败后 1 分钟,然后是 5 分钟、30 分钟、2 小时和 12 小时。这足以覆盖一次部署、一次重启,以及大多数持续一个下午的故障。最后一次尝试之后,该事件会被标记为未送达。

未送达事件与重放

控制面板中的每个端点都有一个未送达事件列表,保留 30 天,并附有最后一次尝试的状态码或错误。端点修复后,可以逐个重放事件,也可以批量选择后重放。重放的事件沿用原始事件 ID,但会获得新的时间戳和签名,因此按事件 ID 去重的处理程序只会处理一次,即使之前某次尝试实际上已经送达你那里。

端点健康状况

同一页面会显示每个端点的成功率、最近一次失败和平均响应时间。如果处理程序需要四秒才能响应,在它开始超时之前,你就能在这里看到。

经得起这一切的处理程序

  1. 先验证。检查 X-Meteor-Signature 标头中的 HMAC-SHA256 签名是否与原始请求体及 X-Meteor-Timestamp 标头相符,并拒绝过旧的时间戳。签名证明事件来自我们;时间戳则可防止其他任何人重放事件。
  2. 快速确认。保存事件并立即返回 200;实际工作放到后台任务中完成。
  3. 去重。保存已处理过的事件 ID,忽略重复事件。重试和重放是正常现象,不是错误。
  4. 按时间而不是到达顺序排序。重放的 message.sent 可能晚于同一条消息的 message.delivered 到达。请按 created_at 和状态优先级排序,并且绝不要把消息从已送达改回已发送。
  5. 监控。针对你自己的错误率设置告警,并在每次事故后检查未送达列表。

生产环境 Webhook 指南为每个步骤都提供了代码。

测试失败路径

使用测试密钥时,Webhook 的触发方式与真实环境完全相同,同样带有签名,但不会实际发送任何消息。可以用它检查处理程序能否验证签名、能否应对重复事件,以及能否保持状态顺序。然后在发送测试消息期间将端点停止几分钟,再让它恢复:重试应当补送错过的事件,你的数据库最终也应处于正确状态。从未送达列表发起的重放行为相同,并沿用原始事件 ID。

使用本文介绍的产品开始发送。一个电子邮箱地址即可开户。费率公开,支持加密货币付款。
开始发送