Shopify Webhook 完整开发指南
Webhook 是 Shopify 与外部系统集成的核心机制——当店铺发生特定事件（订单、产品、客户、库存等变更）时，Shopify 主动推送 HTTP POST 请求到你的接收端点。相比轮询 API：
- 实时：事件发生数秒内推送
- 节省 API 配额：不消耗主要 API 限流
- 可靠：失败自动重试，48 小时窗口
但 Webhook 开发的失败点也很多：签名验证、幂等性、5 秒超时、重试风暴——任意一点处理不当都会导致生产事故。本文按”订阅 → 接收 → 处理 → 监控”展开。
一、Webhook 工作机制
基本流程
店铺事件发生
↓
Shopify 后端构造 payload
↓
HTTP POST → 你的 endpoint URL
↓
你的服务器接收 + 验签 + 处理
↓
返回 HTTP 200（5 秒内）
↓
Shopify 标记成功
失败后的重试
如果你的 endpoint：
- 5 秒内未响应
- 返回非 2xx 状态码
- 网络不可达
Shopify 会自动重试，最多 19 次，分布在 48 小时内。每次重试包含相同 payload + 增加的 X-Shopify-Webhook-Id header（用于幂等判断）。
48 小时后仍失败 → 放弃推送。这是关键风险——如果你的服务器停机 > 48 小时，期间所有 Webhook 永久丢失。
Webhook 与 API 的关系
| 维度 | API 轮询 | Webhook |
|---|---|---|
| 时效性 | 取决于轮询频率 | 秒级 |
| API 配额 | 消耗 | 不消耗 |
| 资源利用 | 大量空轮询 | 仅事件时触发 |
| 复杂度 | 简单 | 中等（需要 endpoint） |
| 可靠性 | 自有控制 | Shopify 重试机制 |
二、常用事件类型
订单事件（最高频）
| Topic | 触发时机 |
|---|---|
| orders/create | 新订单创建（含未支付） |
| orders/updated | 订单任何字段变更 |
| orders/paid | 支付完成 |
| orders/cancelled | 订单取消 |
| orders/fulfilled | 订单全部发货 |
| orders/partially_fulfilled | 部分发货 |
| orders/edited | 订单内容被修改 |
| refunds/create | 退款创建 |
产品 / 库存事件
| Topic | 触发时机 |
|---|---|
| products/create | 产品创建 |
| products/update | 产品更新 |
| products/delete | 产品删除 |
| inventory_levels/update | 库存量变化 |
| inventory_items/create / update / delete | 库存项变... |
十三、相关教程
- Shopify API 深度应用
- Shopify App 开发
- GDPR 合规完整指南
- Shopify Scripts 与 Functions
- Shopify Webhook 官方文档
- Webhook Topics 列表
- Bull Queue 文档
最后更新时间：
2026年6月27日