公共 API 与 Webhooks 结合使用
有变化时(订单、商品、库存、客户)收到通知,再用 API 读取详情,无需每分钟轮询。
思路
Webhooks 负责通知,API 负责取数据。不用每分钟去问有没有新订单,而是订阅事件,收到事件后再用 API 密钥读取详情。
订阅事件
- 进入 独立站 › 网店设置 › Webhooks。
- 用你的
https://地址新建订阅,选择事件:order.created、order.paid、order.cancelled、product.updated、inventory.changed和customer.created。 - 保存签名密钥:只显示一次。
收到事件时
- 校验签名:请求头
X-Bizq-Signature带v1=和用密钥对「X-Bizq-Timestamp、一个点、请求体」计算的 HMAC-SHA256。不匹配或过旧的一律拒绝。 - 立即返回 2xx。否则 BizQ 会在 24 小时内重试。
- 用 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:重试不会产生重复订单。