Webhook 設定與管理
當您的網站上有事情發生時 - 例如買家完成付款、包裹出貨或送達、訪客送出網上表單、寄件網域驗證失效或流量突破里程碑 - Kanorio 可以透過 Webhook 主動把該筆資料即時送到您指定的網址。
把 Webhook 接上 Zapier、Make、n8n 或您自建的系統後,就能免手動把新訂單寫進 Google 試算表、把顧客填表內容轉發到團隊的 Slack/Discord/Telegram 群組、自動建立客服工單,或同步到公司的 ERP 與 CRM。
如果您是負責撰寫接收程式的工程師: 本篇說明後台設定、事件訂閱、重試規則與失敗排查;若要查看 HTTP Headers、
X-Kanorio-Signature簽章驗證程式碼與 8 種事件的完整 JSON 欄位規格,請直接閱讀Webhook 事件與簽章驗證。
開始前請先確認
- 設定位置:後台左側「網站設定 › 開發者 › Webhooks」。
- 端點數量:所有計劃(含免費版、專業版與商務版)每個網站最多皆可建立 10 個 Webhook 端點。
- 角色權限:只有網站的擁有者與管理員可以新增、測試、修改訂閱、查看送出內容、手動重送與顯示/輪替簽章金鑰;其他團隊成員只看得到端點的顯示名稱與狀態,看不到網址、金鑰與推送紀錄。
新增與測試 Webhook(5 個步驟)
1. 在接收工具取得 HTTPS 接收網址
先打開您用來接收資料的工具,建立一個 Webhook 接收端並複製網址(網址必須以 https:// 開頭,且不能是 localhost 或內部網絡位址):
- Zapier:新增 Zap,Trigger 選「Webhooks by Zapier」→ Event 選「Catch Hook」,複製產生的 Webhook URL。
- Make:新增 Scenario,第一個模組選「Webhooks」→「Custom webhook」,新增並複製網址。
- n8n:新增「Webhook」節點,HTTP Method 選
POST,複製 Production/Test URL。 - 自建系統:由您的工程師提供一個可接收
POSTJSON 請求的https://網址。
2. 在 Kanorio 新增端點
前往「網站設定 › 開發者 › Webhooks」,點選「新增 Webhook」,貼上剛才複製的網址,並填入一個好辨識的顯示名稱(例如「Zapier 訂單同步試算表」「Make 表單轉發群組」),再按「新增 Webhook」。
3. 複製或保存簽章金鑰
建立完成後,畫面會顯示這個端點專屬的「簽章金鑰」(以 whsec_ 開頭):
- 如果您接的是 Zapier、Make、n8n:這類工具的接收網址本身帶有隨機密鑰路徑,通常不需要另外設定簽章驗證,直接按「完成」即可。
- 如果您接的是自建伺服器:請複製這把簽章金鑰交給您的工程師設定驗簽(之後隨時可在列表展開該端點、點選「顯示」再次查看,或點選「產生新金鑰」輪替)。
4. 點選「傳送測試」確認連通
在列表中點開剛建立的端點,按「傳送測試」。系統會立即送出一則測試事件(team.test):
- 畫面顯示「測試成功(HTTP 200,耗時 X ms)」,且您的 Zapier/Make 或伺服器收到測試資料,就代表連線成功。
- 「傳送測試」不會寫入正式推送紀錄,也不會計入連續失敗次數,排查時可以放心多按幾次。
5. 調整要訂閱的事件(選用)
新建立的端點預設會訂閱「全部事件」;若只想讓這個網址收到特定通知(例如只收「訂單付款」),請見下一節調整。
選擇要訂閱的事件
在列表展開任一端點,於「訂閱事件」區塊可選擇:
- 全部事件(預設):目前支援的所有事件都會送出,未來 Kanorio 新增的事件也會自動送出。
- 指定事件:只勾選這個端點需要的事件(至少勾選一項),按「儲存訂閱」立即生效。
目前支援以下正式營運事件與 1 種測試事件(各事件的 JSON 欄位細節請見Webhook 事件與簽章驗證):
| 事件名稱 | 什麼時候會送出? | 事件代碼 |
|---|---|---|
| 訂單付款 | 買家完成付款、訂單正式成立時(每筆訂單送出一次) | ec.order.paid |
| 貨態更新 | 出貨單進入已出貨、已到店、已送達或配送異常時 | ec.shipment.statusChanged |
| 表單回覆 | 訪客送出網上表單且通過防灌水檢查時(含填表人資訊與每一題完整答案) | customers.form.submitted |
| 存取權開通/撤銷 | 學員因購買、免費領取或您手動開通而取得課程或下載包,或存取權被撤銷時 | deliverables.entitlement.granted / revoked |
| 單元完成 | 學員完成課程中的一個單元時(每位學員每個單元送出一次) | deliverables.progress.unit_completed |
| 課程完成 | 學員達到課程的完成條件時(每位學員每門課送出一次) | deliverables.progress.completed |
| 測驗作答 | 學員交出測驗時(含分數與是否及格) | deliverables.quiz.attempted |
| 發出結業證書 | 學員取得結業證書(記下證書編號與發證日期)時;每位學員每門課一次 | deliverables.certificate.issued |
| 資料集合項目變更 | 資料集合單筆項目新增、更新草稿、發佈、取消發佈或刪除時 | collections.item.created / updated / published / unpublished / deleted |
| 資料集合批次變更 | 在後台工作台批次儲存、匯入 CSV/JSON,或透過 API 批次寫入資料集合項目時(合併送出一則) | collections.items.bulk_changed |
| 譯文上線/移除 | 多語言網站某一筆內容在某個語言的譯文單獨上線(校正後儲存、API 寫入、原文改動後的自動補翻)或被移除時;整站翻譯進行中不會逐筆送出 | content.translation.published / deleted |
| 語言上線/下線/更新 | 某個語言對訪客上線(整站翻譯完成或您手動上線)、被移除或停用,或改了網址前綴、自動翻譯開關、順序或主語言時 | localization.locale.published / unpublished / updated |
| 整站翻譯完成/失敗 | 加入語言或「重跑缺的」啟動的整站翻譯結束時(附翻好、略過與失敗的筆數) | localization.job.completed / failed |
| 寄件網域失效 | 您已驗證的自有寄件網域 DNS 驗證失效時(同一網域每天最多一次) | customers.sendingDomain.degraded |
| 寄送額度提醒 | 本期寄信額度用完、觸發自動加購、自動加購達上限或加購扣款失敗時 | customers.messagingQuota.alert |
| 儲存空間提醒 | 儲存空間快滿、已滿、觸發自動加購、自動加購達上限或加購扣款失敗時 | site.storageQuota.alert |
| 年度續期提醒 | 年繳計劃續期前,且有年繳加購或尚未結算的加購費、平台費時(預告合併扣款總額) | site.subscription.upcomingRenewal |
| 加購調價預告 | 加購項目定價調整前(至少提前 30 天) | site.subscription.addOnPriceChange |
| 流量里程碑 | 網站累計瀏覽量突破 100、500 時 | site.analytics.milestone |
| 串接暫停 | 某個 Webhook 端點因連續失敗被系統自動暫停時(會通知其他仍正常的端點,不會送給被暫停的那個端點) | customers.teamDestination.disabled |
| 權限申請 | 團隊成員在後台遇到權限不足、送出權限申請時(每筆申請送出一次) | team.accessRequest.created |
| 測試事件 | 在面板點選「傳送測試」時 | team.test |
Webhook 與「團隊通知 Email」的分工
- 開關獨立管理:要不要送出 Webhook,只看「網站設定 › 開發者 › Webhooks」裡各端點的訂閱設定。「自動化 › 設定」點開自動化後,「送出 Webhook」會顯示「N 個端點已訂閱」或「尚未連接」供您核對,但開關統一在 Webhooks 頁面設定。
- 不會取代原本的團隊 Email:新增 Webhook 後,原本會寄給網站擁有者或團隊名單的通知信(例如新訂單、表單回覆)照樣會寄出。若想關閉團隊 Email、只留 Webhook,請至「購物通知」或「表單確認信」將團隊 Email 開關關閉。
- 不佔用寄信額度:Webhook 是透過 HTTPS 直接推送到外部網址,完全不消耗網站每月的 Email 寄送額度。
查看推送紀錄、手動重送與自動暫停恢復
查看最近推送與「重送」
展開任一端點,下方的「最近推送」會列出最近 10 筆通知的事件名稱、結果狀態(已送出、失敗、處理中)、HTTP 狀態碼與時間;點開單筆紀錄可進一步查看嘗試次數、耗時、下次自動重試時間與失敗原因:
- 查看內容(保存 7 天):通知送出後的 7 天內,您可以點選「查看內容」檢視當時送出的完整 JSON 資料。
- 手動重送(保存 7 天):若接收端曾短暫故障或流程設定剛修好,7 天內的通知隨時可點選「重送」再推播一次。手動重送會使用相同的通知編號(方便接收端去重),且如果重送失敗,不會觸發背景重試、也不會計入自動暫停的失敗次數。
送不出去時的自動重試與自動暫停
當您的接收端沒有正常回應時,系統會依回應狀態自動處理:
- 自動退避重試(最多 8 次、約兩天半):
如果接收端超過 8 秒沒有回應、發生網絡錯誤,或回傳 HTTP
429(請求太頻繁)、5xx(伺服器錯誤),Kanorio 會在背景依序自動重試:1 分鐘後 → 5 分鐘後 → 30 分鐘後 → 2 小時後 → 8 小時後 → 24 小時後 → 再 24 小時後,加上首次送出總共最多嘗試 8 次。 - 不重試的錯誤(
3xx與其他4xx): 如果接收端回傳重新導向(301、302等)或設定錯誤(如400、401、403、404),代表網址或驗證設定有問題,系統不會重試,直接計為 1 次推送失敗。 - 立即暫停(
410 Gone): 如果接收端回傳410 Gone,代表對方明確宣告該網址已停用,系統會立即暫停這個端點。 - 連續 3 次失敗自動暫停:
當某個端點連續 3 則通知最終都送不出去(例如重試 8 次用盡仍失敗,或連續 3 次收到
404),系統會將該端點標為「連續失敗,已暫停」,停止繼續推送,並寄送平台通知與 Email 給具「管理串接服務」權限的成員(擁有者、管理員,以及勾選此權限的自訂角色)。 - 如何重新啟用: 確認接收端(或 Zapier/Make 流程)修復後,回到「網站設定 › 開發者 › Webhooks」展開該端點,先按「傳送測試」確認回應正常,再按「重新啟用」即可恢復推送(失敗計數會自動歸零)。
常見推送失敗原因與排查方式
在「傳送測試」或「最近推送」看到失敗訊息時,可對照下表快速排查:
| 後台顯示的失敗原因 | 代表什麼意思? | 建議處理方式 |
|---|---|---|
| 接收端超過 8 秒沒有回應 | 接收端處理太久才回傳結果 | 請工程師將接收端改為「收到請求驗證無誤後先回傳 200 OK,再於背景處理後續耗時工作(如寫入資料庫或寄信)」 |
| 接收端回應了重新導向,Kanorio 不會跟隨 | 網址回傳了 301、302、307 或 308 | 常見於網址少加/多加了結尾斜線 /、或網址被導向新網域。請將 Webhook 網址直接改成最終的 https:// 網址 |
| 接收端的 SSL 憑證無效或已過期 | 接收端網址的 HTTPS 憑證未正確安裝、已過期或為自簽憑證 | 請更新接收端伺服器的 SSL/TLS 憑證(必須為公開受信任憑證機構簽發) |
| 查不到這個網址的網域 | DNS 解析不到該網址的網域 | 檢查 Webhook 網址是否拼錯字,並確認該網域的 DNS A/CNAME 記錄已生效 |
| 無法連線到接收端 | 接收端伺服器未啟動,或防火牆擋下了連線 | 確認伺服器正在運行,且防火牆已放行下方列出的 Kanorio 兩個固定來源 IP |
| 接收端拒絕了這個請求(HTTP 401 / 403) | 接收端的身分驗證或驗簽未通過 | 若接自建伺服器,請確認接收端的簽章金鑰與 Kanorio 面板上的金鑰一致,且驗簽時使用的是原始請求內容(Raw Body) |
| 接收端找不到這個網址(HTTP 404) | 網址路徑不存在,或 Zapier/Make 的流程尚未開啟 | 檢查網址是否填錯;若使用 n8n 的 Test URL 或 Make,確認已在對方介面開啟監聽或正式啟用流程 |
| 接收端暫時限制了請求次數(HTTP 429) | 接收端(或 Zapier/Make 免費額度)達到頻率上限 | 系統會自動排程重試;若頻繁發生,請檢查接收端工具的計劃額度或放寬限流 |
| 接收端發生錯誤(HTTP 5xx) | 接收端伺服器內部程式報錯(如 500、502、503) | 請查看接收端伺服器的錯誤日誌(Error Logs),修復後在 Kanorio 點選「重送」 |
接收端有防火牆時(固定來源 IP 白名單)
Kanorio 的所有 Webhook 請求(包含首次推送、傳送測試、手動重送與背景自動重試)皆固定從以下兩個 IPv4 位址輪流發出。若您的公司伺服器或防火牆設有來源白名單,請將兩個 IP 都加入放行清單:
| 固定出口 IP(IPv4) |
|---|
137.184.250.60 |
167.99.28.231 |
安全提醒:IP 白名單僅作為網絡層的額外防護,不能取代簽章驗證。自建接收端請務必一併驗證
X-Kanorio-Signature。若未來我們需要新增或更換出口 IP,會提前在本頁公告並保留新舊 IP 並行期。
與工程師交接(簽章金鑰與網站 ID)
如果您請內部或外包工程師開發接收程式,只需要在後台準備兩項資訊交給工程師,並附上Webhook 事件與簽章驗證這篇技術文件連結:
- 端點的「簽章金鑰(
whsec_...)」: 在「網站設定 › 開發者 › Webhooks」展開該端點,於「簽章金鑰」區塊點選「顯示」即可複製。- 懷疑金鑰外流或定期更換時:點選「產生新金鑰」。換發後,舊金鑰在 24 小時內仍然有效(期間每則請求會同時附上新舊兩把金鑰算出的簽章),讓工程師有 24 小時可以零停機更新伺服器設定;若在 24 小時內再按一次「產生新金鑰」,上一把舊金鑰就會立即作廢。
- 網站 ID(
websiteId): 如果您的伺服器同時接收多個 Kanorio 網站的 Webhook,可根據 JSON 內的websiteId欄位分辨是哪個網站。您可以在後台「網站設定 › 一般」頁面最底部直接複製該網站的websiteId。
網址、簽章金鑰與 7 天內的推送內容皆採用 Google Cloud 信封加密保存,且每次在面板顯示金鑰或查看內容都會留存稽核紀錄(詳見金鑰與憑證如何保管)。
常見問題
不會受影響。Webhook 在免費版、專業版與商務版皆支援最多 10 個端點與事件細部過濾;變更或取消計劃後,您設定的網址、顯示名稱、事件訂閱與簽章金鑰都會照常運作。
當接收端回應超過 8 秒、網絡瞬斷,或有人在後台點選「重送」時,同一則通知就會再送一次。重試與重送都會帶上完全相同的通知編號(Header 的 X-Kanorio-Delivery 與 JSON 的 id),請您的工程師或自動化流程用這個編號檢查是否已處理過。
Kanorio 目前對外推播採用標準 JSON 格式的通用 Webhook。若要轉發到 Slack、Discord、Telegram、Microsoft Teams 或 Google 試算表,建議將 Webhook 先接到 Zapier、Make 或 n8n,再由它們排版並轉發到您團隊慣用的通訊工具。
您可以參考Webhook 事件與簽章驗證內每個事件的完整 JSON 範例;或先建立一個 Webhook 端點並點選「傳送測試」,等真實網站發生一次事件(例如自己送出一筆測試表單)後,直接在後台「最近推送」點選「查看內容」,就能看到實際送出的完整 JSON。