Shopify Webhooks

Shopify Webhook orders/create 收不到

现象#

后台已订阅 orders/create,测试下单后端点无请求。Webhook 列表显示投递失败或从未投递。本地隧道以为连着,实际 Shopify 打到旧 URL。

原因#

订阅地址错误、HTTP 非 200、SSL 问题、应用未卸载重装导致订阅丢失、或事件名/API 版本不匹配。测试店与生产店搞混时也会“收不到”。

步骤#

  1. 在后台或 Partner 应用查看 Webhook 投递日志与最后响应码。
  2. 用cli/隧道确认公网 URL 与订阅一致,更新过期隧道。
  3. 端点先返回 200 再异步处理。
  4. 用 Admin API 列出 webhook 订阅核对 topic。
  5. 对照 Webhook 文档。
  6. 下测试单并在 Asia/Shanghai 记录到达时间。

验收#

连续三笔测试单均在 5 秒内到达且验签通过。

专项深读 · 可复现排查指南

订单 webhook 没收到时的完整排查路径

先确认订阅存在,再确认 Shopify 是否尝试发送,最后检查接收服务是否超时、签名验证失败或处理异常。不要通过客户重复下单来盲目重试。

建议按以下顺序复现和定位

  1. 在 App 配置中核对 orders/create 主题与接收地址,确认端点为公开可访问 HTTPS。
  2. 查看 webhook Delivery 日志与响应码;若没有交付记录,先确认订阅和测试事件是否确实产生。
  3. 确认服务端使用原始请求体与 App secret 验证 HMAC,避免 JSON 重新序列化导致签名不匹配。
  4. 接收端快速返回成功状态,将慢任务放到队列,并建立失败重试与死信记录。
  5. 使用 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 平台能力迭代较快,具体操作路径与字段以官方文档和店铺后台实际版本为准。