> ## Documentation Index
> Fetch the complete documentation index at: https://developers.zangsho.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook 設定
> 設定 Webhook 接收訂單事件通知，含簽章驗證、重試機制與失敗日誌
## 概覽
Webhook 讓帳獸在特定事件發生時（如訂單建立、付款成功、退款），自動向你指定的 URL 發送 HTTP POST 請求。你可以利用 Webhook 串接自動化工作流，例如發送通知、更新內部系統或觸發其他動作。
## 設定 Webhook
登入後台，從側邊欄進入 **Webhook** > **Webhook 設定**。
輸入你的 Webhook 接收端點 URL。
Webhook URL 必須使用 **HTTPS** 協定。不支援 HTTP URL。
勾選你想要接收的事件類型：
| 事件 | 說明 |
| ---------------- | --------- |
| `order.created` | 訂單建立時觸發 |
| `order.paid` | 訂單付款成功時觸發 |
| `order.refunded` | 訂單退款時觸發 |
將啟用開關切換為開啟狀態，點擊**儲存**。
## Webhook Secret
系統會自動為你的商家產生一組 Webhook Secret，用於驗證 Webhook 請求的真實性。
* Secret 在後台以遮蔽方式顯示：`whsec_****abcd`
* 每次 Webhook 請求都會在標頭中附帶簽章
請妥善保管你的 Webhook Secret，不要將其暴露在前端程式碼或公開的版本控制中。
## 簽章驗證
每個 Webhook 請求都會包含 `X-Webhook-Signature` 標頭。你應該在接收端驗證此簽章，確認請求確實來自帳獸：
```javascript Node.js theme={null}
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 });
});
```
```php PHP (Laravel) theme={null}
use Illuminate\Http\Request;
Route::post('/webhook', function (Request $request) {
$signature = $request->header('X-Webhook-Signature');
$payload = $request->getContent();
$secret = config('services.zangsho.webhook_secret');
$expectedSignature = hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expectedSignature, $signature)) {
return response()->json(['error' => 'Invalid signature'], 401);
}
// 處理 Webhook 事件
$event = $request->input('event');
Log::info('收到 Webhook 事件', ['event' => $event]);
return response()->json(['received' => true]);
});
```
務必使用**常數時間比較**（如 `timingSafeEqual` 或 `hash_equals`）來驗證簽章，避免時序攻擊。
## Webhook Payload
以下是 `order.paid` 事件的 Payload 範例：
```json theme={null}
{
"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** 功能來驗證端點配置：
1. 在 Webhook 設定頁面點擊**發送測試**
2. 系統會立即發送一筆測試 Webhook 到你的 URL
3. 頁面會顯示 HTTP 回應狀態碼與回應內容
如果測試成功回傳 200 OK，代表你的端點配置正確。
## 重試機制
當 Webhook 發送失敗時（非 2xx 回應），帳獸會自動進行重試：
* 最多重試 **3 次**
* 重試間隔會遞增
## 失敗日誌
你可以在後台查看所有發送失敗的 Webhook 記錄：
* **日誌保留期限**：90 天
* **篩選條件**：依事件類型、日期範圍、訂單編號篩選
* **詳情展開**：查看完整 Payload、HTTP 回應碼與回應內容
* **單筆重試**：點擊失敗記錄旁的重試按鈕
* **批次重試**：選取多筆記錄後一次重試
## 成功率統計
Webhook 設定頁面提供發送統計資訊：
| 指標 | 說明 |
| ---- | ----------------- |
| 總發送數 | 期間內的 Webhook 發送總數 |
| 成功數 | 回傳 2xx 的次數 |
| 失敗數 | 回傳非 2xx 的次數 |
| 成功率 | 成功數 ÷ 總發送數 × 100% |
成功率顏色標示：
* 🟢 **≥ 95%**：健康
* 🟡 **80% - 94%**：需注意
* 🔴 **\< 80%**：需立即處理
你可以切換查看 **7 天** 或 **30 天** 的統計數據。
## 注意事項
**批次匯入不觸發 Webhook**。透過批次 API（`/customers/batch`、`/orders/batch` 等）匯入的資料不會發送 Webhook 通知。如果需要觸發 Webhook，請使用單筆建立 API。
## 下一步
使用 n8n 或 Make 串接 Webhook 建立自動化工作流。
管理你的 API Token 與權限設定。