Webhooks

当应用处于 HIOBuy 仓配履约（warehouse） 模式时，HIOBuy 会将 履约生命周期事件 推送到你的 HTTPS Endpoint。请在开发者门户 → Webhooks 配置。投递为异步；Public API 响应不会等待你的 Webhook 服务。

前置条件： 渠道授权 / 履约模式需设为 HIOBuy 仓配。自履约（self）应用可在门户看到介绍，但无法创建或启用 Endpoint。

概览 {#overview}

项	说明
传输	向你的 Endpoint `POST` JSON
超时	10 秒
成功	HTTP `2xx`
签名密钥	`whsec_…`（创建 / 轮换时仅展示一次）
签名头	`HioBuy-Signature`
事件 ID 头	`HioBuy-Event-Id`
User-Agent	`HioBuy-Webhooks/1.0`
重试	最多 5 次：立即，然后 1m / 5m / 30m / 2h
测试事件	门户发送测试事件 → `livemode: false`，id 前缀 `evt_test_`

Endpoint 注册、密钥轮换、投递历史与手动重试均为 门户能力（会话鉴权）。v1 没有 Public /v1/webhooks/* 管理接口。

事件目录 {#events}

按 Endpoint 订阅，至少选择 1 个事件。

分组	事件类型	触发时机
采购	`procurement.failed`	仓配采购失败
采购	`procurement.out_of_stock`	采购缺货
入仓	`package.received`	国内包裹入库
入仓	`package.exception`	入仓异常（`data.exception_type`）
合包	`consolidation.completed`	合包完成，可出库
出库	`shipment.created`	国际运单创建
出库	`shipment.dispatched`	已交运
出库	`shipment.delivered`	已签收
出库	`shipment.exception`	出库/物流异常（`data.exception_type`）
账户	`balance.low`	仓配钱包低于阈值

Warehouse → 开发者的线上推送会逐步开通；当前请用门户 发送测试事件 验证接收端与验签。

公共 Envelope {#envelope}

每次投递的 Body 均为如下 JSON：

{
  "id": "evt_01HXYZ…",
  "type": "package.received",
  "created_at": "2026-08-16T04:00:00.000Z",
  "livemode": true,
  "app_id": "app_…",
  "data": {
    "package_id": "pkg_…",
    "order_id": "ord_…",
    "status": "received"
  }
}

字段	类型	说明
`id`	string	公共事件 ID（正式 `evt_…`，测试 `evt_test_…`）
`type`	string	事件类型
`created_at`	string	ISO-8601 时间
`livemode`	boolean	门户测试事件为 `false`
`app_id`	string	你的 App ID
`data`	object	事件业务字段（不含仓配内部字段）

`data` 示例 {#data-shapes}

以下与门户测试样例一致；正式事件使用相同字段名与生产 ID。

procurement.failed

{
  "order_id": "ord_…",
  "status": "failed",
  "reason": "supplier_rejected"
}

package.exception

{
  "package_id": "pkg_…",
  "order_id": "ord_…",
  "status": "exception",
  "exception_type": "DAMAGED"
}

shipment.dispatched

{
  "shipment_id": "shp_…",
  "tracking_number": "…",
  "status": "dispatched"
}

balance.low

{
  "available_amount": 12.5,
  "currency": "USD",
  "threshold": 50
}

HTTP 投递 {#delivery}

POST /your/webhook-path HTTP/1.1
Host: your-server.example
Content-Type: application/json
User-Agent: HioBuy-Webhooks/1.0
HioBuy-Event-Id: evt_01HXYZ…
HioBuy-Signature: t=1723780800,v1=abcdef0123456789…

生产环境 Endpoint 必须使用 HTTPS。非生产环境可使用 http://localhost / 隧道域名做本地调试。
请在 10 秒内返回 2xx。其他状态码或网络错误会进入重试（直至次数用尽）。
投递为 至少一次。请用 id（以及可选的 HioBuy-Event-Id）做幂等去重。

签名校验 {#signature}

读取 HioBuy-Signature（t=<unix_seconds>,v1=<hex_hmac>）。
构造待签字符串："{t}.{raw_body}"，其中 raw_body 必须是收到的原始 Body（UTF-8 JSON 原文）。
计算 HMAC-SHA256(secret, signed_payload)，结果做 hex。
与 v1 做常量时间比较。
若 |now - t| 过大则拒绝（建议容忍 5 分钟），降低重放风险。

Node.js 示例

import crypto from "node:crypto";
 
function verifyHioBuySignature(rawBody, signatureHeader, secret, toleranceSec = 300) {
  const match = /^t=(\d+),v1=([0-9a-f]+)$/i.exec(signatureHeader || "");
  if (!match) return false;
 
  const t = Number(match[1]);
  const expected = match[2].toLowerCase();
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
 
  const signed = `${t}.${rawBody}`;
  const digest = crypto
    .createHmac("sha256", secret)
    .update(signed, "utf8")
    .digest("hex");
 
  const a = Buffer.from(digest, "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

whsec_… 密钥仅保存在你的服务端。门户列表只展示掩码（whsec_••••… + 末 6 位）。可随时轮换；请在下次投递前更新服务端配置。

重试与投递状态 {#retries}

尝试	相对上次失败的延迟
1	立即（入队）
2	1 分钟
3	5 分钟
4	30 分钟
5	2 小时

最终失败后状态为 failed。可在门户投递详情中 立即重试 重新入队。

投递状态：pending · success · retrying · failed。

门户接入步骤 {#portal}

在渠道授权 / 履约配置将应用设为 仓配履约。
打开 Webhooks → 添加 Endpoint。
填写 HTTPS URL、可选描述，并勾选事件。
在密钥展示时立刻复制保存（仅一次）。
使用 发送测试事件，查看最近投递与 attempt 记录。
按需轮换密钥、停用或删除 Endpoint。

限额与保留 {#limits}

限制	值
Payload 大小	≤ 64 KB
单次 attempt 存档的响应体	≤ 4 KB
事件 / 投递保留	约 30 天
Attempt 保留	约 14 天

获取支持

需要集成帮助？请联系开发者支持 support@hiobuy.com · 预计 1–2 个工作日内回复

发送邮件