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": "新訂單 #1024，NT$1,280",
  "summary": "「我的商店」收到一筆已付款的訂單。",
  "fields": [{ "label": "訂單編號", "value": "#1024" }],
  "data": { "…": "依事件而異，見下方事件參考" },
  "actionUrl": "https://app.kanorio.com/store/transactions?tx=…"
}

事件參考

以下為各事件的 data 欄位。「可空」表示該欄位可能為 null。

ec.order.paid 訂單付款

買家完成付款、訂單成立時發送；每筆訂單發送一次。

ec.shipment.statusChanged 貨態更新

出貨單進入出貨、到店、送達或配送異常時發送；同一張出貨單的每個貨態各發送一次。

customers.form.submitted 表單回覆

訪客提交表單且通過垃圾判定時發送；每筆回覆發送一次。

answers[] 的每一項：

customers.sendingDomain.degraded 寄件網域失效

已驗證的自有寄件網域驗證失效時發送；同一個網域每天最多發送一次。

customers.messagingQuota.alert 寄送額度提醒

寄送額度狀態變更時發送。

site.analytics.milestone 流量里程碑

網站累計瀏覽量突破里程碑時發送，每個里程碑發送一次。

customers.teamDestination.disabled 串接暫停

某個 Webhook 端點被自動暫停時發送（連續失敗達門檻或接收端回傳 410）。僅會發送至其他正常的端點。

team.test 測試事件

點擊「傳送測試」時發送，僅發送一次、不重試、不寫入推送紀錄。

確認請求來自 Kanorio

驗證方式：

1. 從 X-Kanorio-Signature 取出 t 與所有 v1。
2. 將 t、一個英文句點與原始請求內容（未經解析、重新序列化的 raw body）串接，例如 1790000000.{"version":"1",…}。
3. 使用簽章金鑰對該字串計算 HMAC-SHA256（十六進位），並與任一個 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 等服務通常無處編寫驗證邏輯；其接收網址本身包含隨機路徑，通常不需額外驗證簽章。

更換簽章金鑰

簽章金鑰可在串接列表展開該端點後，點擊「顯示」查看。若懷疑金鑰外流，請點擊「產生新金鑰」：

• 舊金鑰在 24 小時內仍有效，期間每則請求會同時附上新舊兩個簽章（兩個 v1），任一相符即可。
• 請於 24 小時內將接收端更新為新金鑰。面板將顯示舊金鑰的到期時間。
• 若於 24 小時內再次點擊「產生新金鑰」，舊金鑰將立即失效。

相關文件

• 開發者
• 自動通知
• 紀錄：查看每一次寄給顧客與團隊的通知
• 方案比較