Webhook

網站上發生的事，Kanorio 可以即時通知您的系統：買家付款、包裹出貨或送達、訪客送出表單、寄件網域失效、寄送額度用完、流量突破里程碑。接上 Zapier、Make、n8n 或您自己的程式後，就能自動寫進試算表、轉發到團隊的聊天群組、建立客服工單，或同步到您的 ERP、CRM。

設定位置在網站主控台的技術設定，「串接」分頁。Webhook 是商務版功能，只有網站的擁有者與管理員可以新增或管理；其他成員看不到網址、金鑰與推送紀錄。

新增 Webhook

1. 在接收端建立一個接收網址。例如 Zapier 選「Webhooks by Zapier」的「Catch Hook」，Make 選「Webhooks」的「Custom webhook」，n8n 新增「Webhook」節點。網址必須以 https:// 開頭。
2. 到主控台的「技術設定」，切到「串接」分頁。
3. 按「新增 Webhook」，貼上網址。可以另外取一個好認的名稱，例如「Zapier 訂單流程」。
4. 按「新增 Webhook」。畫面會顯示這個端點的「簽章金鑰」，需要驗證請求來源的話，請複製起來設到接收端（見下方「給工程師」）。
5. 按「傳送測試」。接收端收到一則「Kanorio 測試事件」，畫面也會顯示回應的狀態碼與耗時，就代表連接成功。

每個網站最多可以新增 5 個 Webhook。

選擇要送的事件

每個端點展開後都有「訂閱事件」：

• 全部事件（預設）：目前有的事件都送，日後新增的事件也會自動送。
• 指定事件：只勾您要的事件，按「儲存訂閱」。

目前有這些事件（欄位細節見文末「事件參考」）：

要不要送 Webhook 只看這裡的訂閱。自動通知的各情境面板會顯示「N 個端點已訂閱」或「尚未連接」，但開關在這裡，不在自動通知。

Webhook 不會取代寄給您的 Email。加了 Webhook 之後，原本會寄給擁有者的通知信照樣會寄出，例如新訂單與表單回覆；貨態更新的團隊 Email 預設就是關閉的。要開或關哪些團隊 Email，請在「自動通知」設定。

送不出去時

• 接收端回應錯誤（HTTP 429 或 5xx）或 8 秒內沒有回應，Kanorio 會自動重試：1 分鐘後、5 分鐘後、30 分鐘後、2 小時後、8 小時後、24 小時後、再 24 小時後，總共最多送 8 次，前後約兩天半。
• 接收端回應其他 4xx（例如 404、401）代表設定有問題，不會重試。
• 接收端回應 410 Gone 代表您不想再收，這個端點會立即暫停。
• 連續 3 次通知都送不出去（重試用盡也失敗），這個端點會自動暫停，避免一直送到失效的網址。擁有者與管理員會收到通知。
• 確認接收端恢復正常後，展開該端點，先按「傳送測試」，成功後再按「重新啟用」。

每個端點展開後都看得到「最近推送」：事件、結果、HTTP 狀態與時間；再展開每一筆可以看嘗試次數、耗時、下次重試時間與錯誤原因。7 天內的通知可以「查看內容」看送出的資料，也可以按「重送」再送一次；重送用同一個通知編號，接收端可以用它判斷是否重複。

「傳送測試」不會計入失敗次數，排查時可以放心多按幾次。

接收端有防火牆時

Kanorio 從固定的 IP 送出 Webhook。若您的接收端只允許白名單來源，請把以下三個 IPv4 全部加入（首次送出、測試與手動重送來自前兩個，自動重試來自第三個）：

白名單只是額外的防護，不能取代簽章驗證：請一律驗證 X-Kanorio-Signature（見下方「給工程師」）。IP 若需變更，我們會先在這裡公告，並保留新舊 IP 並行一段時間再移除舊的。

給工程師

請求格式

每則通知是一個 POST，Content-Type: application/json，附以下 header：

接收端回應任何 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 訂單付款

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

{
  "event": "ec.order.paid",
  "data": {
    "orderId": "cmk7…",
    "orderNumber": 1024,
    "amount": 128000,
    "currency": "TWD",
    "itemCount": 2,
    "customerName": "王小明",
    "customerEmail": "ming@example.com"
  }
}

ec.shipment.statusChanged 貨態更新

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

{
  "event": "ec.shipment.statusChanged",
  "data": {
    "orderId": "cmk7…",
    "orderNumber": 1024,
    "shipmentId": "cmk8…",
    "status": "AT_STORE",
    "carrier": "PAYUNI_LOGISTICS",
    "trackingNumber": "T1234567890",
    "storeName": "7-ELEVEN 台北門市"
  }
}

customers.form.submitted 表單回覆

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

answers[] 的每一項：

{
  "event": "customers.form.submitted",
  "data": {
    "formId": "cmk9…",
    "formName": "聯絡我們",
    "submissionId": "cmka…",
    "submitter": { "name": "王小明", "email": "ming@example.com", "phone": null },
    "answers": [
      { "fieldId": "f_name", "type": "name", "label": "姓名", "value": "王小明", "display": "王小明" },
      { "fieldId": "f_email", "type": "email", "label": "Email", "value": "ming@example.com", "display": "ming@example.com" },
      { "fieldId": "f_topic", "type": "choice", "label": "想了解", "value": ["報價", "合作"], "display": "報價、合作" },
      { "fieldId": "f_msg", "type": "long_text", "label": "留言", "value": "想詢問企業方案", "display": "想詢問企業方案" },
      { "fieldId": "f_file", "type": "file", "label": "附件", "value": ["cmkb…"], "display": "需求書.pdf" }
    ]
  }
}

customers.sendingDomain.degraded 寄件網域失效

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

{ "event": "customers.sendingDomain.degraded", "data": { "domain": "mail.example.com" } }

customers.messagingQuota.alert 寄送額度提醒

寄送額度狀態變化時送出。

{
  "event": "customers.messagingQuota.alert",
  "data": { "reason": "exhausted", "quota": 1000, "levels": 0, "periodStart": "2026-09-01T00:00:00.000Z" }
}

site.analytics.milestone 流量里程碑

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

{ "event": "site.analytics.milestone", "data": { "milestone": 500 } }

customers.teamDestination.disabled 串接暫停

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

{
  "event": "customers.teamDestination.disabled",
  "data": { "destinationId": "cmkc…", "failures": 3, "lastError": "HTTP 503" }
}

team.test 測試事件

按「傳送測試」時送出，只送一次、不重試、不寫入推送紀錄。

{ "event": "team.test", "data": { "test": true } }

確認請求來自 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 小時內再按一次「產生新金鑰」，上一把舊金鑰會直接失效。

相關文件

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