Webhook介绍

Webhook简介

Webhook 是一个API 概念，是微服务 API 的使用范式之一，适用于商店发生特定事件后执行代码的应用程序。避免了应用程序定期轮询特定事件。每当事件发生时，都会主动向端点发送一个webhook。

Webhook 订阅

Webhook订阅声明了应用接收某个主题的 Webhook 的意图。订阅的定义如下：

• 事件名称

• 订阅端点

端点是Mshop向其发送 Webhook 的目的地。

相关接口

说明	请求方法	接口地址
获取 Webhook 列表	GET	/openapi/{api_version}/webhooks
获取 Webhook 数量	GET	/openapi/{api_version}/webhooks/count
获取指定 Webhook	GET	/openapi/{api_version}/webhooks/{id}
创建 Webhook	POST	/openapi/{api_version}/webhooks
更新 Webhook	PUT	/openapi/{api_version}/webhooks/{id}
删除 Webhook	DELETE	/openapi/{api_version}/webhooks/{id}

Webhook 响应信息头

每个 webhook 由 Headers 和 Payload 组成。Headers 包含有关 Webhook 的元数据，例如安装应用程序的商店以及API版本。

示例响应头：
X-Hotishop-Topic: orders/create
X-Hotishop-Hmac-Sha256: XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=
X-Hotishop-Shop-Domain: johns-apparel.hotishop.com
X-Hotishop-API-Version: 2021-08
X-Hotishop-Webhook-Id: b54557e4-bdd9-4b37-8a5f-bf7d70bcd043

标头	说明
X-Hotishop-Topic	订阅的事件
X-Hotishop-Hmac	使用 HTTPS 传输时进行验证
X-Hotishop-Shop-Domain	用于识别事件关联的商店
X-Hotishop-API-Version	生成 Webhook的API版本
X-Hotishop-Webhook-Id	用于识别唯一的 webhook

Hmac 生成与校验

<?php

define('HOTISHOP_APP_SECRET', 'my_shared_secret');

function verify_webhook($data, $hmac_header)
{
  $calculated_hmac = base64_encode(hash_hmac('sha256', $data, HOTISHOP_APP_SECRET, true));
  return hash_equals($hmac_header, $calculated_hmac);
}

$hmac_header = $_SERVER['HTTP_X_HOTISHOP_HMAC_SHA256'];
$data = file_get_contents('php://input');
$verified = verify_webhook($data, $hmac_header);
error_log('Webhook verified: '.var_export($verified, true)); //check error.log to see the result
?>

Webhook 失败重试机制

首次发送失败后，按以下规则重发：

1分钟、5分钟、10分钟、30分钟、1小时、2小时。后续都以2小时为间隔发送，直到重发19次。

每5次发送一次告警邮件，最后一次失败后发送 webhook 删除提示邮件。

Webhook 事件支持

我们目前已支持的事件列表：

事件对象	事件	说明
Checkout	checkouts/create	v1.28已支持
	checkouts/update	v1.28已支持
	checkouts/delete	v1.28已支持
Collection	collections/create	v1.25 已支持
	collections/update	v1.25 已支持
	collections/delete	v1.25 已支持
Customer	customers/create	1.27 已支持
	customers/update	1.27 已支持
	customers/delete	1.27 已支持
Order	orders/cancelled	v1.23 已支持
	orders/cancel_refunded	1.27 已支持
	orders/paid	v1.20 已支持
	orders/refunded	v1.23 已支持
	orders/created	v1.43已支持
	orders/updated	v1.43已支持
Product	products/create	v1.21 已支持
	products/update	v1.21 已支持
	products/delete	v1.21 已支持
Shop	app/uninstalled	v1.20 已支持
	shop/update	1.26 已支持
Theme	themes/create	1.27 已支持
	themes/publish	1.27 已支持
	themes/update	1.27 已支持
	themes/delete	1.27 已支持
Domain	domains/update	v1.27已支持
Price Rules	price_rules/update	v1.27已支持
	price_rules/create	v1.27已支持
	price_rules/delete	v1.27已支持
Stock	stocks/update	v1.39已支持

使用 Webhook注意事项

使用版本

标头X-Hotishop-API-Version表示指定使用哪个版本的 API 来序列化 Webhook 事件负载。

如果应用程序设置为使用不再受支持的 API 版本，则 Mshop将使用最旧稳定版本来来提供支持。

若您的应用需要变更 API 版本，请联系平台的应用管理员进行操作。

版本切换请注意版本切换过程中的数据兼容问题 ，以免您的应用程序出错。

处理重复的 webhook

在极少数情况下，您的应用可能会多次收到相同的 webhook 事件。这种情况下，建议通过将X-Hotishop-Webhook-Id标头与先前事件的X-Hotishop-Webhook-Id标头进行比较来检测重复的 webhook 事件。