Webhook 讓帳獸在特定事件發生時（如訂單建立、付款成功、退款），自動向你指定的 URL 發送 HTTP POST 請求。你可以利用 Webhook 串接自動化工作流，例如發送通知、更新內部系統或觸發其他動作。
設定 Webhook
進入 Webhook 設定頁面
登入後台，從側邊欄進入 Webhook > Webhook 設定。
設定接收 URL
輸入你的 Webhook 接收端點 URL。Webhook URL 必須使用 HTTPS 協定。不支援 HTTP URL。
選擇事件訂閱
勾選你想要接收的事件類型：| 事件 | 說明 |
|---|
order.created | 訂單建立時觸發 |
order.paid | 訂單付款成功時觸發 |
order.refunded | 訂單退款時觸發 |
啟用 Webhook
將啟用開關切換為開啟狀態，點擊儲存。
Webhook Secret
系統會自動為你的商家產生一組 Webhook Secret，用於驗證 Webhook 請求的真實性。
- Secret 在後台以遮蔽方式顯示：
whsec_****abcd
- 每次 Webhook 請求都會在標頭中附帶簽章
請妥善保管你的 Webhook Secret，不要將其暴露在前端程式碼或公開的版本控制中。
簽章驗證
每個 Webhook 請求都會包含 X-Webhook-Signature 標頭。你應該在接收端驗證此簽章，確認請求確實來自帳獸：
const crypto = require('crypto');
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(JSON.stringify(payload))
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// 在你的 Webhook 端點中使用
app.post('/webhook', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const isValid = verifyWebhookSignature(req.body, signature, 'your_webhook_secret');
if (!isValid) {
return res.status(401).json({ error: 'Invalid signature' });
}
// 處理 Webhook 事件
const event = req.body.event;
console.log('收到事件:', event);
res.status(200).json({ received: true });
});
務必使用常數時間比較（如 timingSafeEqual 或 hash_equals）來驗證簽章，避免時序攻擊。
Webhook Payload
以下是 order.paid 事件的 Payload 範例：
{
"event": "order.paid",
"timestamp": "2026-02-09T08:00:00Z",
"data": {
"id": 123,
"order_no": "ORD-20260209-001",
"amount": "1990.00",
"currency": "TWD",
"status": "paid",
"payment_method": "credit_card",
"customer": {
"id": 1,
"email": "wang.xiaoming@example.com",
"name": "王小明"
},
"paid_at": "2026-02-09T08:00:00Z",
"created_at": "2026-02-09T07:55:00Z"
}
}
測試 Webhook
設定完成後，你可以使用測試 Webhook 功能來驗證端點配置：
- 在 Webhook 設定頁面點擊發送測試
- 系統會立即發送一筆測試 Webhook 到你的 URL
- 頁面會顯示 HTTP 回應狀態碼與回應內容
如果測試成功回傳 200 OK，代表你的端點配置正確。
重試機制
當 Webhook 發送失敗時（非 2xx 回應），帳獸會自動進行重試：
失敗日誌
你可以在後台查看所有發送失敗的 Webhook 記錄：
- 日誌保留期限：90 天
- 篩選條件：依事件類型、日期範圍、訂單編號篩選
- 詳情展開：查看完整 Payload、HTTP 回應碼與回應內容
- 單筆重試：點擊失敗記錄旁的重試按鈕
- 批次重試：選取多筆記錄後一次重試
成功率統計
Webhook 設定頁面提供發送統計資訊：
| 指標 | 說明 |
|---|
| 總發送數 | 期間內的 Webhook 發送總數 |
| 成功數 | 回傳 2xx 的次數 |
| 失敗數 | 回傳非 2xx 的次數 |
| 成功率 | 成功數 ÷ 總發送數 × 100% |
- 🟢 ≥ 95%：健康
- 🟡 80% - 94%：需注意
- 🔴 < 80%：需立即處理
你可以切換查看 7 天 或 30 天 的統計數據。
注意事項
批次匯入不觸發 Webhook。透過批次 API（/customers/batch、/orders/batch 等）匯入的資料不會發送 Webhook 通知。如果需要觸發 Webhook，請使用單筆建立 API。
下一步
