Skip to main content

概覽

Webhook 讓帳獸在特定事件發生時(如訂單建立、付款成功、退款),自動向你指定的 URL 發送 HTTP POST 請求。你可以利用 Webhook 串接自動化工作流,例如發送通知、更新內部系統或觸發其他動作。

設定 Webhook

1

進入 Webhook 設定頁面

登入後台,從側邊欄進入 Webhook > Webhook 設定
2

設定接收 URL

輸入你的 Webhook 接收端點 URL。
Webhook URL 必須使用 HTTPS 協定。不支援 HTTP URL。
3

選擇事件訂閱

勾選你想要接收的事件類型:
4

啟用 Webhook

將啟用開關切換為開啟狀態,點擊儲存

Webhook Secret

系統會自動為你的商家產生一組 Webhook Secret,用於驗證 Webhook 請求的真實性。
  • Secret 在後台以遮蔽方式顯示:whsec_****abcd
  • 每次 Webhook 請求都會在標頭中附帶簽章
請妥善保管你的 Webhook Secret,不要將其暴露在前端程式碼或公開的版本控制中。

簽章驗證

每個 Webhook 請求都會包含 X-Webhook-Signature 標頭。你應該在接收端驗證此簽章,確認請求確實來自帳獸:
務必使用常數時間比較(如 timingSafeEqualhash_equals)來驗證簽章,避免時序攻擊。

Webhook Payload

以下是 order.paid 事件的 Payload 範例:

測試 Webhook

設定完成後,你可以使用測試 Webhook 功能來驗證端點配置:
  1. 在 Webhook 設定頁面點擊發送測試
  2. 系統會立即發送一筆測試 Webhook 到你的 URL
  3. 頁面會顯示 HTTP 回應狀態碼與回應內容
如果測試成功回傳 200 OK,代表你的端點配置正確。

重試機制

當 Webhook 發送失敗時(非 2xx 回應),帳獸會自動進行重試:
  • 最多重試 3 次
  • 重試間隔會遞增

失敗日誌

你可以在後台查看所有發送失敗的 Webhook 記錄:
  • 日誌保留期限:90 天
  • 篩選條件:依事件類型、日期範圍、訂單編號篩選
  • 詳情展開:查看完整 Payload、HTTP 回應碼與回應內容
  • 單筆重試:點擊失敗記錄旁的重試按鈕
  • 批次重試:選取多筆記錄後一次重試

成功率統計

Webhook 設定頁面提供發送統計資訊: 成功率顏色標示:
  • 🟢 ≥ 95%:健康
  • 🟡 80% - 94%:需注意
  • 🔴 < 80%:需立即處理
你可以切換查看 7 天30 天 的統計數據。

注意事項

批次匯入不觸發 Webhook。透過批次 API(/customers/batch/orders/batch 等)匯入的資料不會發送 Webhook 通知。如果需要觸發 Webhook,請使用單筆建立 API。

下一步

自動化整合

使用 n8n 或 Make 串接 Webhook 建立自動化工作流。

API 金鑰管理

管理你的 API Token 與權限設定。