Webhook 战争：对抗支付集成中的静默失败

Source: Dev.to

背叛你的设置

我学到的残酷真相是：Webhook 更常以静默方式失败，而不是大声报错。

两个关键的变通方案——应当成为必需

你不知道自己需要的备份轮询器

大多数支付网关文档把这颗宝石埋在小字里：

“设置一个重新查询服务，以固定间隔轮询交易状态。”

这不是建议——而是他们承认 webhook 投递并不可靠。服务器宕机？网络抖动？触发了速率限制？Webhook 就会在虚空中丢失。

我的实现思路（Node.js）：

// Simple poller service (Node.js example)
async function reconcileTransactions() {
  const pending = await getPendingTransactions();

  for (const tx of pending) {
    const status = await paymentGateway.checkStatus(tx.reference);

    if (status.hasChanged()) {
      await processWebhookPayload(status);
      await markAsReconciled(tx.id);
    }
  }
}

// Run every 15 minutes
setInterval(reconcileTransactions, 15 * 60 * 1000);

尾随斜杠的灾难

我遇到的 Apache 陷阱是：当你的 webhook 端点是一个目录（例如 /webhook）时，若缺少斜杠，Apache 会自动重定向到 /webhook/。在此重定向过程中，POST 请求会被转换为 GET，导致你的 webhook 收到空请求，却仍返回 200 OK。

文档中的变通办法：“在 URL 末尾加上斜杠”。
更稳健的做法是修改服务器配置：

# .htaccess – The RIGHT way
RewriteEngine On
RewriteCond %{REQUEST_METHOD} POST
RewriteRule ^webhook$ /webhook/ [L]

或者更简单：

DirectorySlash Off

我见过的真实损失

• SaaS 公司： 因为取消的订阅仍在收费（Webhook 失效），导致每月经常性收入损失 14 千美元。
• 电商店铺： 超过 200 件数字商品在支付成功后未交付。
• 预订平台： 当 webhook 顺序错乱时出现双重预订。

我的 Webhook 检查清单

上线前

• 幂等键（Idempotency Keys）： 能安全地多次处理同一条 webhook。
• 死信队列（Dead Letter Queue）： 将处理失败的 webhook 存入，以便人工审查。
• 签名验证（Signature Verification）： 未经验证的请求绝不可信。
• 完整日志（Complete Logging）： 记录请求体、请求头、处理结果和时间戳。

生产环境监控

• 成功率仪表盘（Success Rate Dashboard）： 实时跟踪投递失败情况。
• 自动对账（Automated Reconciliation）： 每日检查网关数据与本库数据是否一致。
• 告警（Alerting）： 当失败率超过 1 % 时立即通知。
• 手动触发（Manual Trigger）： 能从网关后台重新发送 webhook。

思维方式的转变

把 webhook 通知视为“尽力而为”的提醒，而不是可靠的触发器。让系统能够在它们失效时仍然正常运行。你的支付集成不应是纸牌屋。尾随斜杠的修复和轮询建议只是对更深层架构问题的临时止血。

轮到你了

如果你本周要实现支付集成，请帮个忙：在正式上线前先加入轮询服务。当服务器在高峰期意外重启时，你的未来的自己会感激不已。

继续构建（让 webhook 说实话），
Makai