跳到正文

公共 API 与 Webhooks 结合使用

有变化时(订单、商品、库存、客户)收到通知,再用 API 读取详情,无需每分钟轮询。

思路

Webhooks 负责通知,API 负责取数据。不用每分钟去问有没有新订单,而是订阅事件,收到事件后再用 API 密钥读取详情。

订阅事件

  1. 进入 独立站 › 网店设置 › Webhooks。
  2. 用你的 https:// 地址新建订阅,选择事件:order.created、order.paid、order.cancelled、product.updated、inventory.changed 和 customer.created。
  3. 保存签名密钥:只显示一次。

收到事件时

  1. 校验签名:请求头 X-Bizq-Signature 带 v1= 和用密钥对「X-Bizq-Timestamp、一个点、请求体」计算的 HMAC-SHA256。不匹配或过旧的一律拒绝。
  2. 立即返回 2xx。否则 BizQ 会在 24 小时内重试。
  3. 用 API 读取详情:例如收到 order.created 后调用 GET /api/v1/public/v1/orders/ID,收到 inventory.changed 后调用 GET /api/v1/public/v1/stock?productId=ID。

建议

  • 同一事件可能到达两次:用 X-Bizq-Delivery-Id 避免重复处理。
  • 作为兜底,定期(例如每晚)用 updatedSince 同步一次,以防漏掉通知。
  • 从网站创建订单请用带 Idempotency-Key 的 POST /orders:重试不会产生重复订单。
返回帮助中心