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 固定住的版本不是一回事。