Shopify Webhook orders/create 收不到
现象#
后台已订阅 orders/create,测试下单后端点无请求。Webhook 列表显示投递失败或从未投递。本地隧道以为连着,实际 Shopify 打到旧 URL。
原因#
订阅地址错误、HTTP 非 200、SSL 问题、应用未卸载重装导致订阅丢失、或事件名/API 版本不匹配。测试店与生产店搞混时也会“收不到”。
步骤#
- 在后台或 Partner 应用查看 Webhook 投递日志与最后响应码。
- 用cli/隧道确认公网 URL 与订阅一致,更新过期隧道。
- 端点先返回 200 再异步处理。
- 用 Admin API 列出 webhook 订阅核对 topic。
- 对照 Webhook 文档。
- 下测试单并在 Asia/Shanghai 记录到达时间。
验收#
连续三笔测试单均在 5 秒内到达且验签通过。
专项深读 · 可复现排查指南
订单 webhook 没收到时的完整排查路径
先确认订阅存在,再确认 Shopify 是否尝试发送,最后检查接收服务是否超时、签名验证失败或处理异常。不要通过客户重复下单来盲目重试。
建议按以下顺序复现和定位
- 在 App 配置中核对 orders/create 主题与接收地址,确认端点为公开可访问 HTTPS。
- 查看 webhook Delivery 日志与响应码;若没有交付记录,先确认订阅和测试事件是否确实产生。
- 确认服务端使用原始请求体与 App secret 验证 HMAC,避免 JSON 重新序列化导致签名不匹配。
- 接收端快速返回成功状态,将慢任务放到队列,并建立失败重试与死信记录。
- 使用 webhook ID/业务订单 ID 做幂等保护,重复事件不会再次创建 ERP 订单。
可参考的示例(非真实客户环境)
// Node.js:处理顺序示意(不是完整的应用路由)
// 1) 接收 rawBody(Buffer),而非重新 JSON.stringify 对象
// 2) 验证 X-Shopify-Hmac-Sha256
// 3) 对 webhook ID / order ID 去重
// 4) 将事件放入队列,然后及时返回 200
// 5) 队列任务更新 ERP,并保留失败日志注意:不要在接收到请求时立刻执行耗时的库存同步或 ERP 写入。Shopify 可能重试已发送的事件,必须按幂等方式处理。
交付与验证记录应该包含什么
测试正常、重复、签名错误和接收端暂时不可用四个场景,确认没有丢单、重复单或未授权事件入库。
原始技术资料:Shopify / Google 官方文档。本节为根据公开文档整理的排查方法与模拟示例,未宣称来自客户项目或已在您的店铺实测。
本文由 风格技术 技术团队整理,适用于 Shopify 标准版与 Plus 店铺。Shopify 平台能力迭代较快,具体操作路径与字段以官方文档和店铺后台实际版本为准。