[!info] related notes

• 所属 MOC: Shopify MOC
• 相关 API: Shopify Admin API
• 应用场景: Shopify 应用

Shopify Webhook

一句话定义

Webhook 是事件驱动的 HTTP 回调，当 Shopify 商店发生特定事件时，Shopify 自动向你的服务器发送 POST 请求，实现实时数据同步。

核心机制

工作流程

Shopify 商店发生事件（如新订单）
  ↓
Shopify 触发 Webhook
  ↓
发送 POST 请求到你的服务器
  ↓
你的服务器处理事件
  ↓
返回 200 OK（确认收到）

常见 Webhook 事件

订单相关

• orders/create - 新订单创建
• orders/updated - 订单更新
• orders/paid - 订单支付完成
• orders/cancelled - 订单取消

产品相关

• products/create - 新产品创建
• products/update - 产品更新
• products/delete - 产品删除

客户相关

• customers/create - 新客户注册
• customers/update - 客户信息更新

库存相关

• inventory_levels/update - 库存变化

最小例子

注册 Webhook

mutation {
  webhookSubscriptionCreate(
    topic: ORDERS_CREATE
    webhookSubscription: {
      format: JSON
      callbackUrl: "https://your-app.com/webhooks/orders"
    }
  ) {
    webhookSubscription {
      id
    }
  }
}

接收 Webhook（Node.js）

app.post('/webhooks/orders', async (req, res) => {
  const order = req.body;
  
  // 验证 Webhook 签名
  const hmac = req.headers['x-shopify-hmac-sha256'];
  if (!verifyWebhook(req.body, hmac)) {
    return res.status(401).send('Invalid signature');
  }
  
  // 处理订单
  console.log(`New order: ${order.id}`);
  await saveOrderToDatabase(order);
  
  // 必须返回 200
  res.status(200).send('OK');
});

最佳实践

1. 异步处理：收到 Webhook 后立即返回 200，异步处理业务逻辑
2. 验证签名：确保请求来自 Shopify
3. 幂等性：同一事件可能发送多次，做好去重
4. 快速响应：5 秒内返回 200，否则 Shopify 认为失败

Related notes

• Shopify MOC
• Shopify Admin API
• Shopify 应用