Webhook 詳解:簽名負載與重試策略

Backend2026-11-12TryQuickToolBox

您已經建立了一個 API,它會發送 Webhook 來通知外部服務有關事件。但當接收端點故障時會發生什麼事?或者當惡意行為者試圖偽造 Webhook 請求時?如果沒有適當的防護措施,您的 Webhook 可能會成為資料不一致和安全漏洞的來源。本文說明如何實作簽名負載和重試機制,讓您的 Webhook 既可靠又安全。

什麼是 Webhook,為什麼它們需要安全性?

Webhook 是由特定事件觸發的使用者定義 HTTP 回呼。它們能實現系統之間的即時通訊,例如在下單時通知支付服務。然而,由於 Webhook 是公開可存取的端點,它們容易受到欺騙和重播攻擊。此外,網路問題或接收方停機可能導致事件遺失。因此,必須解決兩個關鍵問題:真實性(透過簽名負載)和可靠性(透過重試)。

簽名負載:確保真實性和完整性

簽名負載允許接收方驗證 Webhook 是否來自受信任的來源,以及資料是否未被篡改。這通常使用 HMAC(基於雜湊的訊息驗證碼)和共享密鑰來實現。

HMAC 簽名如何運作

發送方和接收方共享一個密鑰。對於每個 Webhook 請求,發送方使用密鑰和請求負載(通常包含時間戳以防止重播攻擊)計算 HMAC 簽名。簽名會放在標頭中傳送,例如 X-Signature。接收方重新計算簽名並與收到的簽名進行比較。如果它們匹配,則請求是真實的。

以下是使用 HMAC-SHA256 的 Python 範例:

import hmac
import hashlib
import time

secret = b'your_shared_secret'
payload = b'{"event":"order.created","id":123}'
timestamp = str(int(time.time())).encode()
message = timestamp + b'.' + payload
signature = hmac.new(secret, message, hashlib.sha256).hexdigest()

# Send headers: X-Signature: signature, X-Timestamp: timestamp

在接收方,驗證簽名並檢查時間戳以確保請求是最近的(例如,在 5 分鐘內)。這可以防止重播攻擊。

簽名負載的最佳實踐

重試機制:確保可靠傳遞

即使有簽名負載,網路故障或接收方錯誤也可能導致 Webhook 傳遞失敗。穩健的重試策略能確保事件最終被傳遞,同時不會壓垮接收方。

設計重試策略

一種常見的方法是帶抖動的指數退避。例如,在 1 分鐘後重試,然後 5 分鐘,然後 30 分鐘,直到達到最大嘗試次數(例如 5 次)。在負載中包含唯一的事件 ID,以便接收方可以去重。

重試排程範例:

嘗試次數延遲
1立即
21 分鐘
35 分鐘
430 分鐘
52 小時

在耗盡重試次數後,將事件移至死信佇列以供手動檢查。

冪等性:處理重複傳遞

由於重試可能導致重複傳遞,接收方必須具有冪等性。在負載中包含事件 ID,並讓接收方儲存已處理的 ID 以忽略重複項。或者,設計操作本身俱有冪等性(例如,使用 PUT 而不是 POST)。

實作 Webhook:逐步指南

  1. 定義事件和負載結構: 記錄您的系統發出的事件以及每個事件的 JSON 結構描述。
  2. 生成密鑰: 為每個 Webhook 端點建立唯一的密鑰並安全地共享它。
  3. 對每個請求簽名: 對負載和時間戳計算 HMAC,並包含在標頭中。
  4. 實作帶退避的重試: 使用佇列系統來排程重試。
  5. 提供驗證簽名的方法: 為接收方記錄驗證過程。
  6. 監控和記錄: 追蹤傳遞嘗試和失敗以進行除錯。

常見陷阱及如何避免

常見問題

什麼是簽名 Webhook 負載?

簽名 Webhook 負載包含加密簽名(例如 HMAC),允許接收方驗證發送方的真實性和資料完整性。

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

通常使用指數退避重試 3 到 5 次。具體次數取決於您的 SLA 和事件的關鍵性。

我可以使用 JWT 而不是 HMAC 來簽署 Webhook 嗎?

是的,可以使用 JWT,但 HMAC 更簡單且更常用於 Webhook 簽名。JWT 會增加額外開銷,更適合用於驗證權杖。

準備好測試您的 Webhook 負載了嗎?使用我們的 JSON 格式化工具 在發送前驗證和美化您的 JSON 負載。