ウェブフック

アプリが HIOBuy 倉庫フルフィルメント（warehouse） モードのとき、HIOBuy は フルフィルメントのライフサイクルイベント を HTTPS エンドポイントへ配信します。Developer Portal → Webhooks  で設定してください。配信は非同期で、Public API の応答は Webhook サーバーを待ちません。

前提条件: チャネル認可 → フルフィルメントモード = HIOBuy warehouse。セルフモードではポータルの案内は見られますが、Endpoint の作成・有効化はできません。

概要 {#overview}

登録、シークレットのローテーション、配信履歴、手動再試行は ポータル専用（セッション認証）です。v1 に Public /v1/webhooks/* 管理 API はありません。

イベント一覧 {#events}

Endpoint ごとに購読します。少なくとも 1 件必要です。

倉庫→開発者への本番プッシュは段階的に展開されます。まずはポータルの テスト送信 で受信側を検証してください。

公開エンベロープ {#envelope}

各配信ボディは次の 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"
  }
}

data の例 {#data-shapes}

以下はポータルテストのサンプルです。本番も同じキーを使います。

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 URL は HTTPS 必須。非本番では http://localhost / トンネルホストを許可する場合があります。
• 10 秒以内に 2xx を返してください。それ以外やネットワークエラーは再試行対象です。
• 配信は 少なくとも 1 回。id（および任意で HioBuy-Event-Id）で冪等化してください。

署名検証 {#signature}

1. HioBuy-Signature を読む（t=<unix_seconds>,v1=<hex_hmac>）。
2. 署名対象文字列を構築: "{t}.{raw_body}"。raw_body は受信した 生 のボディ（UTF-8 JSON 原文）。
3. HMAC-SHA256(secret, signed_payload) を計算し hex 化。
4. v1 と定数時間比較。
5. |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_… はサーバー側のみ保存。ポータル一覧はマスク表示（末尾 6 桁）。ローテーション後は次の配信前にサーバーを更新してください。

再試行と配信ステータス {#retries}

最終失敗後は failed。ポータルの配信詳細から 今すぐ再試行 で再キューできます。

配信ステータス: pending · success · retrying · failed。

ポータル手順 {#portal}

1. チャネル認可 / フルフィルメント設定 でアプリを 倉庫フルフィルメント に設定。
2. Webhooks  を開き → エンドポイントを追加。
3. HTTPS URL、任意の説明、購読イベントを入力。
4. 表示された署名シークレットをすぐにコピー（一度のみ）。
5. テストイベント送信 で最近の配信 / attempt を確認。
6. 必要に応じてシークレットのローテーション、無効化、削除。

制限と保持 {#limits}

関連

• フルフィルメント設定 — 倉庫モード
• フルフィルメント API — 国際出荷ルート
• 認証 — API キー（Webhook シークレットとは別）
• Sandbox — サンドボックス注文は自動プッシュしません。ポータルのテスト送信を使用