Webhook 詳解:簽章載荷與可靠重試
你發布了支付整合功能,在預備環境中一切正常。但到了生產環境,一位客戶完成付款,你的端點卻逾時兩秒,訂單始終沒有啟用。同時,支付供應商對同一個事件重試了三次,而你的應用程式為那個成功的事件建立了三筆重複訂單。Webhook 看起來很簡單——不過是一個 HTTP POST——但真正困難的部分在於信任與交付保證。
本文探討最常導致 Webhook 整合失敗的兩件事:驗證請求確實來自發送方,以及處理重試時不產生重複的副作用。
Webhook 究竟是什麼
Webhook 是一種反向 API 呼叫。與其讓你的伺服器每分鐘輪詢供應商詢問「有什麼新消息嗎?」,不如由供應商在事件發生時,主動推送 HTTP 請求到你註冊的 URL。載荷通常是 JSON,事件類型則位於請求主體或標頭中。
POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592
{
"id": "evt_8f2c1a",
"type": "payment.succeeded",
"created": 1735689600,
"data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}發送方有兩個設計決策很重要,評估任何供應商時都應檢查這兩點:它是否對載荷簽章?它是否在失敗時重試?
未簽章 Webhook 的危險
你的 Webhook URL 是公開的。任何知道這個 URL 的人都可以 POST 一個偽造的 payment.succeeded 事件,將未付款的訂單標記為已付款。IP 允許清單有一點幫助,但供應商會更換 IP、運行於 CDN 之後,而且你可能拿不到穩定的清單。
穩健的解決方案是使用只有你和供應商知道的共享密鑰,對原始請求主體進行 HMAC 簽章。供應商計算簽章並在標頭中發送;你重新計算並比對。
正確驗證簽章
有三個細節很容易出錯:
- 使用原始主體。驗證之後才解析 JSON。重新序列化已解析的物件會改變空白與鍵順序,簽章將永遠無法匹配。
- 以常數時間比較。天真的字串比較會洩漏時間資訊。使用時間安全函式。
- 將時間戳納入簽章字串。對
timestamp.body簽章可讓你拒絕舊請求並阻止重放攻擊。
// Node.js / Express 範例
const crypto = require('crypto');
function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
header.split(',').map(p => p.split('='))
);
const timestamp = Number(parts.t);
if (!timestamp) return false;
// 拒絕過期請求(重放防護)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - timestamp) > toleranceSeconds) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1 || '');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
return res.status(401).send('invalid signature');
}
const event = JSON.parse(req.body.toString());
// ... 處理事件
res.status(200).send('ok');
});注意 express.raw() 中介軟體。如果你在此路由之前掛載了 express.json(),主體已經被解析,簽章檢查會無聲地失敗——這是非常常見的錯誤。
設計不遺失事件的重試機制
Webhook 交付是「至少一次」,而非「恰好一次」。網路會故障,你的部署會重啟容器,供應商無從得知你的 200 回應是否真實。因此供應商會以指數退避重試,通常持續數小時或數天。
快速回應,稍後處理
你的端點應做最少的事:驗證、持久化原始事件、回傳 2xx。繁重的工作——發送電子郵件、呼叫其他 API、產生發票——應在背景任務中進行。若處理時間超過供應商的逾時限制,請求會被視為失敗並重試,即使你已完成工作。
- 驗證簽章與時間戳。
- 將事件插入資料表,並對事件 ID 設定唯一約束。
- 立即回傳
200。 - 非同步處理已儲存的事件,並標記為完成。
冪等性:解決重複問題的真正方法
由於重試會發生,你的處理程序必須能安全地執行兩次。事件 ID 是天然的冪等鍵。
INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;若插入影響零行,表示你已見過此事件——確認並繼續。對於業務邏輯,套用相同概念:啟用付款時使用訂單 ID 作為唯一鍵,這樣第二個事件就無法建立第二次啟用。
刻意選擇狀態碼
| 狀態碼 | 供應商行為 | 使用時機 |
|---|---|---|
| 200 / 204 | 標記為已交付 | 事件已接受(即使已處理過) |
| 400 | 通常不重試 | 格式錯誤且永遠無法處理的載荷 |
| 401 | 通常不重試 | 簽章不符——檢查你的密鑰 |
| 429 | 以退避重試 | 你正在進行速率限制 |
| 500 / 503 | 以退避重試 | 暫時性失敗、資料庫故障、部署進行中 |
對無法儲存的事件回傳 200 是最糟的選擇:供應商停止重試,事件永遠消失。回傳 5xx,讓重試發揮作用。
生產環境實用檢查清單
- 僅使用 HTTPS;絕不接受純 HTTP 的 Webhook。
- 將簽章密鑰儲存在密鑰管理員中並支援輪換——許多供應商允許兩個作用中的密鑰。
- 記錄每個請求的事件 ID、類型、簽章結果與處理結果。
- 設定容差視窗(通常五分鐘)以阻擋重放。
- 在資料庫層級使處理程序冪等,而不僅在應用程式碼中。
- 當失敗率或處理延遲超過閾值時發出警報。
- 為支援人員提供手動重放端點。
在本機測試 Webhook
你無法輕易在 localhost 上接收公開的 POST。選項包括:暴露開發連接埠的通道工具、供應商的 CLI(若有),或一個小型腳本向你的處理程序發送簽章載荷,以便你演練驗證路徑。
最有價值的測試是重複事件:發送同一個事件兩次,確認你的系統最終狀態相同。然後發送一個帶有舊時間戳的事件,確認它被拒絕。再篡改主體的一個位元組,確認簽章檢查失敗。
除錯載荷
Webhook 主體是 JSON,格式錯誤或深度嵌套的載荷在日誌中很難閱讀。格式化工具能幫助你在撰寫解析程式碼之前快速檢視結構。JSON 格式化工具 在瀏覽器中執行,因此你可以貼上擷取的載荷,而不會將客戶資料傳送到伺服器。
常見問題
Webhook 與 API 有何不同?
API 是拉取式:你的程式碼在需要資料時呼叫供應商。Webhook 是推送式:供應商在事件發生時呼叫你的端點。大多數整合兩者並用——Webhook 用於事件通知,API 用於取得完整詳細資訊或執行操作。
為何我的 HMAC 簽章永遠不符?
常見原因是對重新序列化的主體簽章,而非原始位元組。空白、鍵順序與 Unicode 轉義都會改變雜湊值。在任何 JSON 中介軟體之前讀取原始請求主體,並確認密鑰與雜湊演算法符合供應商文件。
Webhook 重試有保證嗎?
沒有。供應商通常會在有限視窗內以指數退避重試,然後放棄。將 Webhook 視為快速通知管道,而非真實來源:定期與供應商的 API 對帳,讓遺漏的事件最終得到修正。
如果你今天正在建立或除錯 Webhook 接收器,請先鎖定簽章驗證與冪等儲存——這兩項變更就能消除現實世界中大多數的 Webhook 事故。