Shopify webhook 订阅要指定 API 版本吗

现象#

同一次订阅在不同时间创建的 webhook 返回字段不一样，代码解析时偶尔报字段缺失。

原因#

• webhook 订阅绑定了创建时的 API 版本
• 应用升级了 API 版本但旧订阅未重建
• 不同环境订阅的版本不一致

处理步骤#

1. 创建订阅时显式传 webhookSubscriptionCreate(topic:, webhookSubscription: {callbackUrl, format}) 并使用当前 API 版本路径
2. 升级 API 版本时批量重建订阅
3. 在 payload 处理里对字段做兼容读取
4. 记录每条订阅的版本，纳入发布检查清单

验收标准#

同一 topic 的 payload 结构一致，升级后无字段缺失报错，订阅版本可查询。