简体中文

English

简体中文

English

显示模式

Genstore Webhook ​

Webhook 是一种在特定事件发生时，系统自动向指定的 URL 发送通知的技术。在 Genstore 中，开发者可以通过订阅特定的 Webhook 主题来实时接收商店内发生的事件，如订单创建或产品更新。与需要应用主动发起的 REST API 不同，Webhooks 让应用能够被动地接收由平台推送的事件通知，极大地提高了数据处理的效率。

使用场景举例 ​

例如，应用需实时同步商店订单，鉴于 REST API 的调用频次有限，建议您在安装应用时订阅 Webhook 主题 " 订单创建（orders/create）"。这样，每当有新订单生成，您的应用会即刻接收到通知，有效减少对 REST API 的依赖，并大幅提升数据同步的时效性。

WARNING

  • Webhook 事件通知无法保证顺序性。
  • 通知连续失败 8 次后，系统将不再尝试发送，可能导致数据丢失。

关键概念 ​

Webhook 主题 ​

Webhook 主题定义事件类型。开发者可根据需要订阅一个或多个主题，当相应事件触发时，应用将收到即时通知。

Webhook 主题会以业务域归类。

Webhook 订阅 ​

Webhook 订阅是开发者声明接收特定主题事件的过程。订阅时需提供：

  • 订阅的主题名
  • 接收通知的 HTTPS 端点

更多信息，可查阅 Webhook 订阅

Webhook Headers ​

每条 Webhook 通知均包括标准的 Header（消息头）和 Payload（消息体）。Header 中包含主题名、签名、商店域名等关键信息，以确保数据传输安全。

bash
X-Genstore-Topic: `orders/create`
X-Genstore-Hmac-Sha256: `4iiJMXWsseFppeH5Jo4by6OsHH3cmAMeJAwLMeiZKwP=`
X-Genstore-Shop-Domain: `{shop}.genmystore.com`
X-Genstore-API-Version: `202412`
X-Genstore-Webhook-Id: `bf5l8lbcd088-4b87-6a5f -bdd9-b58557e8 `
X-Genstore-Triggered-At: `2024-12-30T23:59:59.888889999Z`
X-Genstore-Event-Id: `8c9f0dx091b5-b7ad-88c8-7008-98887460 `

其中，

  • X-Genstore-Topic：Webhook 主题名
  • X-Genstore-Hmac-SHA256：签名验证
  • X-Genstore-Shop-Domain：店铺的域名
  • X-Genstore-API-Version：API 版本
  • X-Genstore-Webhook-Id：应用订阅 Webhook 的唯一 ID
  • X-Genstore-Triggered-At：事件消息的触发时间
  • X-Genstore-Event-Id：事件消息的唯一 ID

REST API 请求轮询与 Webhook 事件通知对比 ​

REST API 请求轮询 ​

应用需频繁请求 REST API 以查询新订单，这种方式虽简单但效率低下，易造成资源浪费。

Webhook 事件通知 ​

应用通过订阅 Webhooks，当相关事件（如新订单）触发时，Genstore 会主动推送通知。