Webhooks 詳解:簽名載荷與重試機制實現可靠整合

Backend2026-11-13TryQuickToolBox

你剛剛建立了一個端點來接收支付供應商的 Webhook。第一次測試運作正常,但在生產環境中你發現事件遺失、重複扣款,而且無法辨別請求是否真實。Webhook 概念簡單,但要正確實作卻很棘手。本指南說明如何使用簽名載荷保護 Webhook,並實作穩健的重試邏輯,讓你的整合不會默默失效。

什麼是 Webhook,為何重要

Webhook 是由事件觸發的使用者定義 HTTP 回呼。你的應用程式不需輪詢 API 來檢查變更,而是當事件發生時,服務主動將資料推送到你的端點。這讓整合更有效率且近乎即時。

常見使用案例包括支付通知(如 Stripe)、CI/CD 觸發(如 GitHub)和訊息平台(如 Slack)。但這種推送模式讓你無法控制請求到達的時間。這就是為什麼你需要明確處理安全性和可靠性。

安全問題:未簽名的 Webhook 很危險

未簽名的 Webhook 只是對公開 URL 的 HTTP POST。任何人都可以發送看起來像是來自你的支付供應商的請求。若無驗證,攻擊者可以偽造事件,導致欺詐訂單、資料洩露或未授權操作。

解決方案是對載荷進行簽名。發送方使用共享密鑰對請求主體計算加密簽名,並將其包含在標頭中。你的端點重新計算簽名並進行比較。如果匹配,你就知道請求是真實的且未被篡改。

如何使用 HMAC 簽名 Webhook 載荷

HMAC(基於雜湊的訊息驗證碼)是 Webhook 簽名的標準。它使用密鑰和雜湊函數(如 SHA-256)產生對載荷和密鑰唯一的簽名。

以下是發送方在 Python 中簽名載荷的範例:

import hmac
import hashlib
import json

secret = b'your_shared_secret'
payload = json.dumps({'event': 'payment.success', 'amount': 1000}).encode('utf-8')
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()
# Include signature in header: X-Signature: 

在接收方,你必須在處理載荷前驗證簽名:

import hmac
import hashlib

def verify_signature(payload, received_signature, secret):
    expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received_signature)

重要: 始終使用常數時間比較函數如 hmac.compare_digest 來預防時序攻擊。同時,要對原始請求主體驗證簽名,而非解析後的版本,因為 JSON 序列化可能不同。

簽名載荷的最佳實踐

處理失敗:重試與冪等性

Webhook 可能失敗:你的伺服器可能宕機、網路可能中斷,或你的端點可能返回錯誤。可靠的發送方會重試交付,但你必須設計接收方來處理重複和亂序事件。

重試策略

大多數 Webhook 供應商使用帶抖動的指數退避。例如,在 1 分鐘後重試,然後 5 分鐘,然後 30 分鐘,直到最大嘗試次數。這讓你的系統有時間恢復而不會不堪重負。

如果你正在建構發送方,請實作一個帶有排程重試的佇列。儲存載荷和嘗試次數,並使用工作執行緒處理重試。

冪等性:安全重試的關鍵

因為重試可能導致重複交付,你的端點必須是冪等的。這意味著多次處理同一事件應與處理一次具有相同效果。

常見方法:

以下是 Python 中一個簡單的冪等性檢查:

def process_event(event_id, payload):
    if db.exists('processed_events', event_id):
        return  # already processed
    # process payload
    db.insert('processed_events', event_id)

確保檢查和處理在同一個事務中進行,以避免競爭條件。

比較:輪詢 vs. Webhook

方面輪詢Webhook
延遲取決於間隔(如 5 分鐘)近乎即時
伺服器負載即使無變更也持續請求僅在事件發生時請求
複雜度易於實作需要簽名、重試、冪等性
可靠性你控制重試取決於發送方的重試策略

逐步指南:實作安全的 Webhook 接收器

  1. 設定 HTTPS 端點,接受 POST 請求並讀取原始主體。
  2. 提取簽名標頭(如 X-Signature)和時間戳標頭(若存在)。
  3. 驗證簽名 使用 HMAC 和你的密鑰。若無效則拒絕。
  4. 檢查時間戳 以防止重放攻擊(如拒絕超過 5 分鐘的請求)。
  5. 解析載荷 並提取事件 ID。
  6. 檢查冪等性 在資料庫中查詢事件 ID。
  7. 處理事件 在一個同時記錄事件 ID 的事務中進行。
  8. 快速返回 2xx 狀態 以確認接收。如果處理需要時間,將作業加入佇列並返回 202 Accepted。

測試你的 Webhook 實作

使用 ngrok 等工具公開你的本地伺服器並模擬 Webhook。為簽名驗證、冪等性和重試邏輯編寫單元測試。例如,測試重複的事件 ID 被忽略,以及無效簽名返回 401。

除錯時,記錄收到的載荷和簽名(但絕不記錄密鑰)。如果你處理 JSON 載荷,JSON 格式化工具 可以幫助你快速檢查和驗證結構。

常見問題

什麼是簽名的 Webhook 載荷?

簽名載荷包含一個加密簽名(通常是 HMAC),使用共享密鑰對請求主體計算。接收方驗證簽名以確保請求真實且未被篡改。

Webhook 應該重試多少次?

沒有通用數字,但常見做法是 3–5 次重試並使用指數退避。之後,事件通常標記為失敗,可能需要手動干預或進入死信佇列。

我可以不使用 HTTPS 使用 Webhook 嗎?

絕不應透過純 HTTP 使用 Webhook。沒有 TLS,攻擊者可以攔截載荷和簽名,並重放或修改請求。始終使用 HTTPS。

準備好檢查和格式化 Webhook 載荷了嗎?試試我們的免費 JSON 格式化工具,立即驗證和美化 JSON 資料。