如何在 Stripe Webhook 恢复后可靠重试丢失事件-php教程-PHP中文网

如何在 Stripe Webhook 恢复后可靠重试丢失事件

stripe 官方 webhook 不支持“批量补发”已错过的事件；其重试机制仅针对单次 http 失败（如超时或非 2xx 响应），且重试事件类型有限（如 setup_intent.created），无法保证补全 payment_intent 或 checkout 相关事件。

stripe 官方 webhook 不支持“批量补发”已错过的事件；其重试机制仅针对单次 http 失败（如超时或非 2xx 响应），且重试事件类型有限（如 setup_intent.created），无法保证补全 payment_intent 或 checkout 相关事件。

在基于 Stripe 构建支付系统时，Webhook 是接收异步事件（如 payment_intent.succeeded、checkout.session.completed）的核心通道。但需明确一个关键事实：Stripe 的 Webhook 重试机制并非“故障恢复工具”，而是面向单次请求失败的补偿策略——它不会在你的服务恢复后自动推送此前因网络中断、服务宕机或 webhook 被动禁用而遗漏的所有事件。

? 重试机制的真实行为

Stripe 对每个事件最多重试 3–5 次（间隔呈指数退避），前提是：

你的 endpoint 返回了非 2xx HTTP 状态码（如 400、500），或
请求在 30 秒内未完成响应（超时）。

⚠️ 但以下情况不会触发重试：

Webhook 在 Stripe Dashboard 中状态为 Disabled（手动关闭或连续失败被自动停用）；
你的服务器完全不可达（DNS 失败、连接拒绝、防火墙拦截）；
服务短暂离线后重启，但期间事件已被 Stripe 标记为“交付失败并放弃”。

正如实测所验证：即使主动对 payment_intent.created 等关键事件返回 400，Stripe 也极少重发同类型事件；反而可能重发无关的 setup_intent.created —— 这并非设计缺陷，而是其幂等性与事件生命周期管理的体现。

Agent Browser

一款AI工具，主要用于一款基于 Rust 的快速无头浏览器自动化命令行工具（CLI），支持 Node.js 回退机制，可使 AI agent 通过结构化命令实现页面导航、点击、输入及截图，适合需要提升相关任务效率的用户。

下载

✅ 正确的补救方案：主动拉取 + 幂等处理

要确保事件不丢失，必须放弃依赖“被动重试”，转为主动、可审计、幂等的事件同步策略：

启用 Stripe Events API + 时间窗口拉取
使用 GET /v1/events 接口，按时间范围查询未处理事件：
```
curl "https://api.stripe.com/v1/events?created[gte]=1717027200&created[lt]=1717113600&limit=100" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Stripe-Version: 2024-06-20"
```
✅ 建议：在服务启动时，从上次成功处理的 event.created 时间戳起，向后拉取最近 24–72 小时事件，避免漏单。

强制幂等性：用 idempotency_key 或事件 id 去重
所有事件处理逻辑前，先检查数据库是否已存在该 event.id：

# Python 示例（Django/Flask 场景）
event = stripe.Event.retrieve(event_id)
if ProcessedEvent.objects.filter(stripe_event_id=event.id).exists():
    return HttpResponse("Already processed", status=200)

# 处理业务逻辑...
ProcessedEvent.objects.create(
    stripe_event_id=event.id,
    type=event.type,
    data=event.data.object
)

监控与告警闭环
- 记录 Webhook 接收日志（含 event.id、type、HTTP 状态、耗时）；
- 设置 Prometheus + Grafana 监控 4xx/5xx 响应率、平均延迟；
- 当连续 5 分钟无新事件写入，触发 Slack 告警（提示可能 webhook 断连）。

? 不推荐的做法（已验证无效）

重启 stripe listen（如 nohup ./stripe listen --forward-to ... &）：该 CLI 工具仅用于本地开发调试，不保存历史事件，也不触发补发；
依赖 Stripe Dashboard 中点击 “Retry” 按钮：仅对单个已知失败事件有效，无法批量操作；
期望 Stripe 支持“Replay all missed events”功能：截至 Stripe API v2024-06-20，该功能不存在。