Webhooks 詳解:簽名負載與重試機制

Backend2026-11-16TryQuickToolBox

你剛剛整合了支付供應商或 CI/CD 服務,現在需要接收即時事件。Webhooks 是系統之間推送資料的標準方式,但許多實作在生產環境中因安全缺陷或不可靠的交付而失敗。本指南說明如何使用簽名負載保護 Webhooks,並實作強健的重試機制。

什麼是 Webhooks 以及為何重要

Webhook 是一種 HTTP 回呼:當來源系統發生事件(例如新訂單)時,它會向您提供的 URL 發送 HTTP POST 請求。與輪詢不同,Webhooks 效率高且近乎即時。然而,由於它們基於 HTTP,您必須明確處理安全性和可靠性。

常見用例包括支付通知、CI/CD 管道觸發、聊天通知以及 SaaS 應用程式之間的資料同步。

使用簽名負載保護 Webhooks

Webhooks 是公開可存取的端點,因此攻擊者可以發送偽造請求。為了防止這種情況,供應商會使用密鑰對每個負載進行簽名。接收方驗證簽名以確保真實性和完整性。

HMAC 簽名如何運作

最常見的方法是 HMAC-SHA256。供應商使用共享密鑰計算請求主體的雜湊值,並將其包含在標頭中(例如 X-Signature)。接收方重新計算雜湊值並進行比較。

// Node.js 範例:產生簽名
const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = JSON.stringify({ event: 'order.created', id: 123 });
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
// 在標頭中發送簽名:X-Signature: sha256=...

在接收方驗證簽名

始終使用常數時間比較以防止計時攻擊。在 Node.js 中,使用 crypto.timingSafeEqual。

// Express.js 中介軟體範例
const crypto = require('crypto');

function verifySignature(req, res, next) {
  const signature = req.headers['x-signature'];
  const payload = JSON.stringify(req.body); // 需要原始主體
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
  const received = Buffer.from(signature, 'utf8');
  if (trusted.length !== received.length || !crypto.timingSafeEqual(trusted, received)) {
    return res.status(401).send('Invalid signature');
  }
  next();
}

重要:使用原始請求主體進行驗證,而不是解析後的 JSON,以避免差異。

額外的安全措施

實作可靠的重試

Webhooks 可能因網路問題、伺服器停機或錯誤而失敗。供應商通常會使用指數退避重試失敗的交付。作為接收方,您必須具備冪等性並處理重複事件。

設計冪等性

每個 webhook 事件都應該有一個唯一 ID。儲存已處理的 ID 以忽略重複事件。使用具有唯一約束的資料庫或像 Redis 這樣的快取。

// 冪等處理的虛擬碼
if (await redis.exists(`webhook:${event.id}`)) {
  return res.status(200).send('Already processed');
}
await processEvent(event);
await redis.set(`webhook:${event.id}`, '1', 'EX', 86400); // 24小時 TTL

重試策略

供應商通常會以遞增的延遲重試(例如 1秒、5秒、30秒、5分鐘、1小時)。確保您的端點快速回應(在 5 秒內)以避免逾時。如果處理時間較長,請確認收到並非同步處理。

以下是常見重試模式的比較:

模式優點缺點
固定間隔簡單可能對正在恢復的伺服器造成壓力
指數退避在停機期間減少負載對於暫時性錯誤延遲交付
帶抖動的指數退避防止驚群效應稍微複雜一些

監控和死信佇列

記錄所有 webhook 嘗試和失敗。在達到最大重試次數後,將事件移至死信佇列 (DLQ) 以供手動檢查。對高失敗率發出警報。

整合所有內容:逐步實作

  1. 設定一個 HTTPS 端點,接受 POST 請求並讀取原始主體。
  2. 驗證簽名,使用共享密鑰和常數時間比較。
  3. 檢查時間戳以防止重放攻擊(如果提供)。
  4. 確保冪等性,透過檢查事件 ID 與快取或資料庫。
  5. 非同步處理事件,如果可能需要時間;立即回應 200 OK。
  6. 在發送方實作重試邏輯,使用指數退避和抖動。
  7. 監控並警報失敗,並對持續性錯誤使用 DLQ。

常見問題

什麼是簽名 webhook 負載?

簽名負載包含加密簽名(通常是 HMAC),允許接收方驗證請求來自受信任的來源且未被篡改。

如何處理重複的 webhook 事件?

使用負載中提供的唯一事件 ID 來追蹤已處理的事件。將 ID 儲存在資料庫或快取中並設定 TTL 以忽略重複事件。

我的 webhook 端點應該返回什麼?

快速返回 2xx 狀態碼(例如 200 OK)以確認收到。如果處理失敗,返回 5xx 以觸發重試,但僅限於暫時性錯誤。

測試 webhook 負載時,您可能需要檢查 JSON 結構。使用 JSON Formatter 來驗證和美化 webhook 負載,以便更容易除錯。