3
0
0
小氢云管机通知插件使用指南：商品 Webhook 一站式对接
2026-10-20
文章摘要
|
小储云 · 网站插件 V1.0
小氢云管机通知插件
商品事件 Webhook 使用指南
将商城内的商品上架、下架、隐藏、删除、新增与价格变动，实时推送到你的外部系统。 配合 小氢云管机 Bot 平台，几分钟即可搭建接收端，实现多实例、多站点统一管理。
插件能做什么
「小氢云管机通知」（标识符 GoodsWebhook）是一款小储云网站插件。它在后台商品发生关键变更时，通过 HTTP POST + JSON 将事件推送到你配置的接收地址，不修改商品数据、不拦截主流程，适合对接机器人、管机系统、库存中台或自建 API。
小储云后台操作商品
→
插件捕获钩子
→
本地发件箱
→
Webhook POST
→
你的接收端 / Bot 实例
实时通知
上下架、改价等操作后自动推送，无需轮询商城 API。
可观测
面板内查看待投递队列、投递日志与失败原因。
安全可选
支持 HMAC-SHA256 签名与时间戳校验，防篡改与重放。
安装与启用
-
获取安装包
使用官方提供的GoodsWebhook-1.0.0.zip，上传至includes/extend/log/Apply/并重命名为GoodsWebhook.zip，在应用商店执行安装；或解压到站点includes/lib/soft/目录。 -
启用插件
在应用商店将插件状态设为「启用」。仅站长后台可打开配置面板（visit: Admin）。 -
钩子自动注册
正常安装后系统会读取Hook.json并注册商品相关钩子。若手动部署，需同步写入includes/lib/Hook/Hook.json。
安装包
install.json 中 image、url 不能为空；请使用包含图标与开发者主页的完整安装包，避免「参数缺失」报错。
面板配置（推荐流程）
路径：站长后台 → 应用商店 → 小氢云管机通知 → 打开设置面板。
- 在 推荐平台 区域点击「开始开发」，前往 bot.ithxs.com 创建实例并获取 实例编号。
-
填写 链接地址：仅填接收端域名，例如
https://bot.ithxs.com（不要带接口路径）。 -
填写 实例编号：与 Bot 平台中该实例的 ID 一致（如
27）。 - （推荐）填写 签名密钥，与接收端保持一致以便验签。
- 勾选需要订阅的事件，打开 推送开关，点击「保存配置」。
- 点击「发送测试」，确认接收端返回 HTTP 2xx；在「投递日志」中查看记录。
Webhook 地址拼接规则
插件不会要求你手写完整 URL，后端按固定规则拼接：
{链接地址}/api/v1/public/plugin/xqy_webhook_receiver/routes/receive?instance_id={实例编号}
示例：链接 https://bot.ithxs.com + 实例编号 27，实际请求地址为：
https://bot.ithxs.com/api/v1/public/plugin/xqy_webhook_receiver/routes/receive?instance_id=27
保存时系统会自动规范化链接地址（只保留协议、主机与端口），避免重复填写路径导致错误。
事件一览
| 事件名 | 说明 | 典型场景 |
|---|---|---|
goods.listed | 商品上架 | 同步到管机、通知运营群 |
goods.delisted | 商品下架 | 停止售卖、下线货源 |
goods.hidden | 商品隐藏 | 前台不可见状态同步 |
goods.deleted | 商品删除 | 清理外部系统映射 |
goods.created | 商品新增 | 自动建档、初始化库存 |
goods.price_changed | 价格调整 | 成本价/利润/自定义售价变化 |
goods.price_fluctuated | 价格波动 | 系统价格波动日志透传 |
上架 / 下架 / 隐藏 额外字段
除商品 ID、名称外，还会附带：
guest_price：游客售价（与前台游客看到的价格一致）href：商品前台链接，格式{站点}/?mod=route&p=Goods&gid={id}state/prev_state：当前与变更前状态（1 上架 / 2 下架 / 3 隐藏）
同一商品重复上架或下架不会重复推送，避免消息风暴。
请求格式与验签
请求头
| Header | 说明 |
|---|---|
X-Webhook-Id | 事件唯一 ID，重试不变，用于幂等去重 |
X-Webhook-Event | 与 JSON 内 event 一致 |
X-Webhook-Timestamp | Unix 时间戳（秒），重试时会更新 |
X-Webhook-Signature | 配置密钥后存在：sha256=HMAC(secret, ts + "." + 原始body) |
请求体示例（上架）
{
"id": "evt_3f9a1c0b7d2e4a68",
"event": "goods.listed",
"occurred_at": "2026-10-20T10:27:41+08:00",
"data": {
"gid": 12,
"name": "示例商品",
"state": 1,
"prev_state": 2,
"guest_price": 2.2,
"href": "https://your-shop.com/?mod=route&p=Goods&gid=12"
}
}
PHP 验签片段
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
if (abs(time() - (int)$ts) > 300) { http_response_code(401); exit; }
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!hash_equals($expected, $sig)) { http_response_code(401); exit; }
完整字段说明见插件目录 WEBHOOK_EVENTS.md。
接收端开发建议
- 使用 bot.ithxs.com 创建实例，将实例编号填入插件面板。
- 接收接口在 10 秒内 返回 HTTP 2xx；业务可先落库再异步处理。
- 以
X-Webhook-Id做唯一键，重复请求直接 200，实现幂等。 - 验签使用原始请求体，不要先 JSON 解析再重新编码。
- 按
event字段分发处理逻辑，勿依赖到达顺序。
推荐平台提供 Webhook 接收路由与实例隔离，适合多商城、多站点统一接入管机能力。
投递与运维
- 重试：失败按 20s / 40s / 80s / 160s 退避，最多 5 次后标记失败。
- 发件箱：本地最多保留 2000 条待投递；面板可「立即投递」「清除失败事件」。
- 投递日志：每次 HTTP 投递记录成功/失败、状态码与耗时。
- 性能：钩子里只做入队，远程请求在响应后执行，不阻塞后台操作。
常见问题
保存配置提示「配置文件写入失败」？
检查 conf/GoodsWebhook/ 与 includes/extend/log/GoodsWebhook/ 目录属主是否为 PHP 运行用户（如 www），并保证可写。
投递日志为空？
修复前仅记录内部错误。请更新到最新版本后，通过上下架或「发送测试」触发投递，在「投递日志」查看。
安装报缺失 image 参数？
使用包含 icon.png 与完整 install.json（含非空 image、url）的安装包。
会重复收到同一条消息吗？
投递为「至少一次」语义，重试可能导致重复。接收端必须用 X-Webhook-Id 去重。