Webhooks 解析:簽名載荷與重試機制
為什麼 Webhooks 在生產環境中會出問題
你已經建立了一個 webhook 端點,在本機測試過,一切運作正常。但到了生產環境:供應商發送了重複的事件、你的端點逾時,或者攻擊者偽造了請求。突然間,你的整合變得不可靠且不安全。
Webhooks 概念上很簡單——由事件觸發的 HTTP 回呼——但生產級實作需要仔細處理安全性和可靠性。本指南涵蓋兩個關鍵面向:用於驗證真實性的簽名載荷,以及處理失敗的重試策略。
什麼是 Webhooks?
Webhook 是一種使用者定義的 HTTP 回呼。當來源系統中發生事件時(例如付款成功),它會向你提供的 URL 發送 HTTP POST 請求,其中包含有關事件的資料。這種推送模式比輪詢更有效率。
但 webhooks 也帶來了挑戰:
- 安全性:你如何知道請求來自合法的發送者?
- 可靠性:如果你的端點故障或回應緩慢怎麼辦?
- 重複:網路可能導致重試;你可能會多次收到相同的事件。
讓我們先解決安全性問題。
使用簽名載荷保護 Webhooks
簽名載荷使用共享密鑰對請求主體建立密碼學簽名。發送者將此簽名包含在標頭中(例如 X-Signature)。你的端點重新計算簽名並進行比較。如果它們匹配,則請求是真實的。
HMAC 簽名如何運作
大多數供應商使用 HMAC-SHA256。簽名是使用共享密鑰對原始請求主體計算得出的。流程如下:
- 供應商和消費者共享一個密鑰。
- 供應商建立載荷,計算 HMAC-SHA256(secret, payload),並將其放在標頭中發送。
- 消費者接收請求,讀取原始主體,計算相同的 HMAC,並進行比較。
重要:使用完全按照接收到的原始主體——解析並重新序列化 JSON 可能會改變位元組並破壞簽名。
實作簽名驗證
以下是使用 Express 的 Node.js 範例:
const crypto = require('crypto');
const express = require('express');
const app = express();
// 對 webhook 路由使用原始主體解析器
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-signature'];
const secret = process.env.WEBHOOK_SECRET;
const expected = crypto
.createHmac('sha256', secret)
.update(req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send('Invalid signature');
}
// 處理事件
const event = JSON.parse(req.body);
// ... 處理事件
res.status(200).send('OK');
});
始終使用如 crypto.timingSafeEqual 的常數時間比較,以防止時序攻擊。
其他安全考量
- 時間戳驗證:在簽名載荷中包含時間戳,並拒絕舊請求以防止重放攻擊。
- HTTPS:Webhook 端點始終使用 HTTPS。
- 密鑰輪換:支援多個作用中的密鑰,以便在不中斷服務的情況下輪換。
實作可靠的重試
即使端點安全,網路問題或暫時性故障也可能導致 webhook 傳遞失敗。穩健的重試機制可確保事件不會遺失。
發送端重試策略
如果你正在建立 webhook 發送器,請實作帶有抖動的指數退避。例如:
- 重試 1:1 分鐘後
- 重試 2:5 分鐘後
- 重試 3:30 分鐘後
- 重試 4:2 小時後
- 重試 5:24 小時後
加入隨機抖動以避免驚群效應。達到最大嘗試次數後停止並發出警報。
接收端最佳實踐
作為 webhook 消費者,你無法控制發送者的重試策略,但可以讓你的端點更具韌性:
- 快速回應:在處理繁重工作之前,先以 2xx 狀態確認接收。使用佇列。
- 冪等性:優雅地處理重複事件。使用事件 ID 進行去重。
- 監控失敗:記錄失敗並設定警報。
使用冪等性處理重複事件
Webhook 供應商通常會在逾時後重試,因此你可能會多次收到相同的事件。讓你的處理具備冪等性:
- 將已處理的事件 ID 儲存在具有唯一約束的資料庫中。
- 在處理之前,檢查 ID 是否已存在;如果存在,則返回 200 OK 而不重新處理。
- 對於會改變狀態的操作,使用冪等鍵。
使用資料庫唯一索引的範例:
async function handleEvent(event) {
try {
await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
} catch (err) {
if (err.code === '23505') { // 唯一約束違反
return; // 已處理過
}
throw err;
}
// 處理事件
}
比較:Webhook 安全方法
| 方法 | 優點 | 缺點 |
|---|---|---|
| HMAC 簽名 | 完整性強,廣泛支援 | 需要密鑰管理 |
| 基本驗證 | 簡單 | 安全性較低,憑證在標頭中 |
| IP 允許清單 | 易於實作 | IP 可能變更,不夠穩健 |
HMAC 簽名是 webhook 安全性的事實標準。
在本機測試 Webhooks
像 ngrok 或 localtunnel 這樣的工具可以將你的本機伺服器暴露到網際網路進行測試。始終使用模擬失敗來測試簽名驗證和重試邏輯。
當檢查來自 webhooks 的 JSON 載荷時,格式化它們有助於除錯。試試我們的 JSON Formatter 來美化列印並驗證 webhook 載荷。
常見問題
如何驗證 webhook 簽名?
使用共享密鑰對原始請求主體計算 HMAC,然後使用常數時間比較函數將其與簽名標頭進行比較。
如果我的 webhook 端點故障該怎麼辦?
大多數供應商會使用指數退避進行重試。確保你的端點快速返回 2xx 並以非同步方式處理,以最小化停機影響。
我可以不使用簽名嗎?
這有風險。沒有簽名,攻擊者可以偽造請求。始終使用簽名載荷,或至少透過 HTTPS 使用基本驗證。
結論
Webhooks 功能強大,但需要關注安全性和可靠性。實作 HMAC 簽名驗證以確保真實性,並設計你的系統以優雅地處理重試和重複事件。透過這些實踐,你的 webhook 整合將變得穩健且適用於生產環境。