Webhook

受信側からの2xx応答は成功とみなされ、レスポンスボディは無視されます。8秒以内に応答してください。処理に時間がかかる場合は、まず200を返し、非同期で処理を行ってください。Kanorioはリダイレクトに従わないため、3xx応答は失敗として扱われます。

共通構造

すべてのイベントJSONは共通のシェルを共有しているため、受信側の設定は一度で済みます。

{
  "version": "1",
  "id": "3f9c2a…",
  "event": "ec.order.paid",
  "occurredAt": "2026-09-29T12:00:00.000Z",
  "websiteId": "cmk…",
  "title": "New order #1024, NT$1,280",
  "summary": "'My Store' received a paid order.",
  "fields": [{ "label": "Order ID", "value": "#1024" }],
  "data": { "…": "Varies by event, see reference below" },
  "actionUrl": "https://app.kanorio.com/store/transactions?tx=…"
}

イベントリファレンス

以下は各イベントの data フィールドです。「Nullable」はフィールドが null になる可能性があることを示します。

ec.order.paid 注文支払い完了

購入者が支払いを完了した際に送信されます（注文ごとに1回）。

ec.shipment.statusChanged 配送状況更新

発送、到着、配達完了、または例外ステータスになった際に送信されます（配送ごとにステータス変更ごとに1回）。

customers.form.submitted フォーム送信

訪問者がフォームを送信し、スパムチェックを通過した際に送信されます（送信ごとに1回）。

answers[] アイテム：

customers.sendingDomain.degraded 送信ドメイン劣化

認証済みのカスタム送信ドメインの認証が失敗した際に送信されます（ドメインごとに1日1回）。

customers.messagingQuota.alert メッセージングクォータ警告

クォータステータスが変更された際に送信されます。

site.analytics.milestone トラフィックの節目

累計サイト閲覧数が節目を超えた際に送信されます（節目ごとに1回）。

customers.teamDestination.disabled 連携の一時停止

Webhookエンドポイントが自動的に一時停止された際に送信されます（連続失敗または410応答）。他の正常なエンドポイントにのみ送信されます。

team.test テストイベント

「テスト送信」がクリックされた際に送信されます（1回のみ、再試行なし、配信履歴に記録されません）。

Kanorioからのリクエストを検証する

検証手順：

1. X-Kanorio-Signature から t とすべての v1 を抽出します。
2. t、ピリオド、リクエストボディ（未パース、再シリアライズされた生データ） を連結します（例：1790000000.{"version":"1",…}）。
3. 署名シークレットを使用して文字列のHMAC-SHA256（16進数）を計算し、v1 と比較します。一致した場合のみ受け入れます。
4. リプレイ攻撃を防ぐため、5分以上前のタイムスタンプを持つリクエストは拒否してください。再試行や再送信は現在のタイムスタンプを使用するため、この制限を緩和する必要はありません。

Node.jsの例：

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = header.split(",").map((part) => part.split("="));
  const t = parts.find(([key]) => key === "t")?.[1];
  const signatures = parts.filter(([key]) => key === "v1").map(([, value]) => value);
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return signatures.some(
    (v1) => v1.length === expected.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
  );
}

Zapier、Make、n8nなどのサービスは通常カスタム検証ロジックをサポートしていませんが、受信URLにランダムなパスが含まれるため、一般的に検証は不要です。

署名シークレットのローテーション

シークレットは、統合リストのエンドポイントを展開し「表示」をクリックすることで確認できます。漏洩が疑われる場合は「新しいシークレットを生成」をクリックしてください：

• 旧シークレットは24時間有効です。この間、各リクエストには新旧両方の署名（2つの v1）が含まれ、どちらかが一致すれば成功となります。
• 24時間以内に受信側のシークレットを更新してください。パネルには旧シークレットの有効期限が表示されます。
• 24時間以内に再度「新しいシークレットを生成」をクリックすると、前回の旧シークレットは即座に無効になります。

関連ドキュメント

• 開発者
• 自動化
• 記録：顧客やチームへの通知履歴を表示
• 料金比較