Webhooks 詳解:簽名載荷與可靠重試

Backend2026-11-17TryQuickToolBox

你剛剛整合了一個第三方服務,它會向你的端點發送 Webhooks。在測試中一切正常,但在生產環境中,你注意到事件丟失、重複傳遞,甚至偽造請求。Webhooks 概念簡單,但正確實現卻很棘手。本文解釋如何透過簽名載荷保護 Webhooks,並實現可靠的重試邏輯,讓你的整合穩健且可信。

什麼是 Webhooks 以及為何重要

Webhooks 是由事件觸發的使用者定義 HTTP 回呼。你無需輪詢 API 以獲取變更,而是註冊一個 URL,每當事件發生時,服務就會發送帶有事件資料的 POST 請求。這種推送模型降低了延遲和伺服器負載,使其成為支付通知、CI/CD 觸發和聊天訊息等即時整合的理想選擇。

然而,Webhooks 帶來了挑戰:驗證真實性、處理失敗以及確保恰好一次處理。讓我們逐一解決這些問題。

使用簽名載荷保護 Webhooks

如果沒有驗證,任何人都可以向你的 Webhook 端點發送偽造請求。簽名載荷透過在請求標頭中包含使用共享密鑰生成的加密簽名來解決此問題。你驗證簽名以確認請求來自預期的發送者且未被篡改。

HMAC 簽名如何運作

大多數服務使用 HMAC(基於雜湊的訊息驗證碼)與 SHA-256。發送者使用密鑰計算請求主體(有時還包括時間戳)的雜湊,並將其包含在類似 X-Signature 的標頭中。你在自己這邊重新計算雜湊並進行比較。

以下是 Node.js 中的典型驗證流程:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

始終使用時間安全比較以防止時間攻擊。此外,在簽名資料中包含時間戳,並拒絕超過幾分鐘的請求以防止重放攻擊。

簽名驗證的最佳實踐

實現可靠的重試

網路會故障,伺服器會重啟,端點會超時。穩健的 Webhook 系統必須重試失敗的傳遞。但重試可能導致重複,因此你需要冪等性。

重試策略

大多數提供者使用帶有抖動的指數退避。例如,在 1 分鐘後重試,然後 5 分鐘,然後 30 分鐘,直到最大嘗試次數(例如 5 次)。在載荷中包含唯一的事件 ID,以便接收者可以去重。

在接收端,快速回應 2xx 狀態以確認收到,然後非同步處理。如果處理失敗,你不能依賴發送者無限重試——實現自己的死信佇列或警報。

冪等鍵

為了處理重複傳遞,使用冪等鍵(通常是事件 ID)並在合理期間內儲存已處理的 ID。在處理之前,檢查該 ID 是否已見過;如果是,則返回成功而不重新處理。

// 範例:Express 中的冪等性檢查
app.post('/webhook', async (req, res) => {
  const eventId = req.body.id;
  if (await db.seenEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }
  await db.seenEvents.add(eventId);
  // 非同步處理事件
  res.status(200).send('OK');
});

比較:輪詢 vs Webhooks

方面輪詢Webhooks
延遲高(基於間隔)低(近即時)
伺服器負載高(頻繁請求)低(事件驅動)
複雜度易於實現需要簽名驗證和重試
可靠性取決於輪詢頻率取決於重試機制

逐步指南:構建安全的 Webhook 接收器

  1. 設置端點,透過 HTTPS 接受 POST 請求。
  2. 驗證簽名 使用共享密鑰,並以 401 拒絕無效請求。
  3. 檢查時間戳 以防止重放攻擊。
  4. 立即回應 在基本驗證後返回 200 OK,然後非同步處理。
  5. 實現冪等性 使用事件 ID 以避免重複處理。
  6. 記錄和監控 失敗和重試。

常見問題

什麼是簽名 Webhook 載荷?

簽名載荷包含加密簽名(通常為 HMAC),允許接收者使用共享密鑰驗證請求的真實性和完整性。

我應該重試失敗的 Webhook 多少次?

常見做法是使用指數退避重試 3–5 次。之後,將事件移至死信佇列以供手動檢查。

我可以在沒有 HTTPS 的情況下使用 Webhooks 嗎?

不可以,HTTPS 對於保護載荷和簽名免受竊聽和篡改至關重要。始終使用 TLS。

準備好測試你的 Webhook 載荷了嗎?使用我們的 JSON 格式化工具 快速美化並驗證 JSON 載荷。