案例 Stripe webhook 版本升级:endpoint 版本、双投递切换与 stripe-node v23 的坑

2026-11-19 21:04:48

Stripe webhook 版本升级:endpoint 版本、双投递切换与 stripe-node v23 的坑

支付对接里有两套「版本」容易混:请求用的 API 版本,和 webhook endpoint 自己固定住的版本。前者改一行 header 或升个 SDK 就动了,后者不改就一直是旧的,而它决定 Stripe 发给你的 event payload 结构。

参考文档:

  • Webhook versioning:
  • API versions:
  • Changelog:

Stripe 为每个请求选版本的依据依次是:Stripe-Version header、服务端 SDK 固定的版本、账户默认版本。这个版本同时决定请求能带哪些参数、响应里有哪些对象、Stripe.js 返回什么、发给 webhook endpoint 的对象结构,以及自动化的 Billing 操作。

endpoint 版本与 SDK 版本必须对齐

每个 webhook endpoint 都有一个 API 版本,Stripe 按这个版本生成事件 payload。所以升级集成版本时,endpoint 也得跟着升。

用 .NET、Java、Go 这类静态语言 SDK 时,这条是必须满足的约束:endpoint 的 API 版本要和 SDK 的 API 版本一致,否则 SDK 反序列化事件会失败。Node、Python 这类动态类型语言宽容一些,但字段缺失同样会在业务代码里出错。

想彻底绕开 webhook 版本管理,用 thin events:v1 和 v2 资源都会产生 thin event,payload 不带版本,升 API 版本或升 SDK 都不用动 event destination 配置。

acacia 之后的版本节奏

2024-09-30.acacia 之前的每个 API 版本都带破坏性变更。从 acacia 起规则变了:

  • 每月发布新版本,不含破坏性变更,可以放心升,不用改代码;
  • 每年两次 major(Basil、Endive 这类),major 的第一个版本才包含破坏性变更;
  • webhook endpoint 升到同一 major 内的任意版本都是安全的。

判断依据很简单:目标版本和当前版本是否跨了 major。

平滑切换 endpoint 版本

推荐做法是让两个 endpoint 并行一段时间,靠 URL 上的查询参数区分。

1. 建一个 disabled 的新 endpoint

URL 相同,加查询参数区分,比如 https://example.com/webhooks?version=2024-04-10。enabled_events 保持和旧 endpoint 一致,api_version 设成目标版本。非最新版本需要通过 API 指定具体版本号。

2. 先让代码忽略新 endpoint 的事件

这一步不改业务逻辑,只加分支:查询参数是旧版本就照常处理;是新版本就忽略并返回 200,避免 Stripe 因为非 2xx 重试。

app.post('/webhooks', (req, res) => {
const v = req.query.version ?? OLD_VERSION;
if (v === NEW_VERSION) {
return res.sendStatus(200); // 暂不处理
}
// 旧版本照常走
});

3. 启用新 endpoint,开始双投递

启用后每个事件发两次,一次到旧版本,一次到新版本。此时业务仍然只处理旧的那份。

4. 切到处理新版,旧版返回 400

升级 SDK 到目标版本、处理完破坏性变更后改分支:新版本正常处理;旧版本直接返回 400。返回 400 会让 Stripe 自动重试,等于保留了一条回滚路径——出问题时把代码回退,旧 endpoint 的事件还在重投。

5. 观测、回滚、下线

监控一段时间。如果新版事件处理失败:回退代码,禁用新 endpoint,让返回 400 的事件重投,排查后重新启用。

稳定之后必须把旧 endpoint 禁掉。否则旧 endpoint 会一直返回 400 触发重试,长期挂着还可能影响依赖 200 响应的其他集成。注意:endpoint 禁用后,之前返回 400 的事件不会再重投。

thin events 与 snapshot events 的差别

thin event 的 payload 没有版本,因此升 API 版本不用改 destination。代价是字段结构不同:

  • previous_attributes 没了,换成 changes.before / changes.after;changes.after 只包含变更的属性,不是完整对象。
  • 要拿完整对象,调 fetchRelatedObject() 或请求 related_object.url。注意拿到的是最新状态,不是事件发生时的快照。
  • 资源创建这类没有变更值的事件,changes 为 null。

迁移期间,一个动作会同时产生 snapshot 和 thin 两份事件。thin 版本里有个 snapshot_event 字段,存原始 snapshot 事件的 ID,可以拿它做幂等键。

迁移节奏:加 thin webhook 路由 → 按现有订阅建 thin event destination → shadow 模式跑一段 → 用幂等切换 → 下线 snapshot destination。别长期双跑,两套处理逻辑会逐渐分叉,复杂度和成本都上去了。

stripe-node v23 的几个坑

v23 对应 API 版本 2026-09-30.endive,迁移指南:

  • 最低 Node 20。
  • verifyHeader() / verifyHeaderAsync() 以前省略 tolerance 会跳过时间戳校验,现在默认用 Webhook.DEFAULT_TOLERANCE。要保留旧行为必须显式传 0。
  • 顶层方法 stripe.constructEventWithoutVerification() 删除,改用 stripe.webhooks.constructEventWithoutVerification()。
  • Stripe.ErrorType 命名空间删除,改用 Stripe.errors。
  • 响应体读取中断现在抛 StripeConnectionError,不再是 StripeAPIError。
  • V2 的 list 方法返回 Stripe.V2List,分页字段是 next_page_url / previous_page_url。
  • V2 请求的地址参数改成 operation 专属接口,不再共用 Stripe.AddressParam / JapanAddressParam 这类 V1 类型。

endive 本身的破坏性变更包括:从 Checkout Sessions 移除 payment_method_types 参数;从 Payment Intents 和 Setup Intents 移除该参数;从 Payment Methods 移除 PayTo 相关字段;Payment Evaluation 的 signal score 改为可空;废弃 payment request button;新增 Standalone 3D Secure API;允许的支付方式里加入 card-present 类型。完整列表见 changelog:

上线前检查清单

  • 确认当前 endpoint 固定的 API 版本,和目标版本是否跨 major
  • .NET / Java / Go:endpoint 版本与 SDK 版本逐一对齐
  • 新 endpoint 先 disabled 建好,enabled_events 与旧端点一致
  • 代码分支按 ?version= 区分新旧,新版本先返回 200
  • 双投递期间确认两份事件都能收到、都能验签
  • 切换后旧版本返回 400,回滚路径验证过一次
  • 旧 endpoint 已禁用,不存在长期 400 重试
  • thin 迁移:changes.before/after 替代 previous_attributes,完整对象走 fetchRelatedObject()
  • thin 迁移用 snapshot_event 做幂等键
  • verifyHeader 是否显式传了 tolerance
  • 事件 ID 字段用 VARCHAR(255) COLLATE utf8_bin 存储,Stripe ID 最长 255 字符
  • webhook listener 对未知事件类型做优雅忽略

还有一条容易漏:通过 API 读取的 event,结构由事件发生时的账户默认 API 版本决定,和 endpoint 固定住的版本不是一回事。

复制全文 生成海报 stripe 支付 webhook 接口对接

推荐文章

程序员茄子在线接单