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

Backend2026-11-14TryQuickToolBox

你已經建置了一個 API,現在需要在事件發生時通知其他服務。輪詢效率低下,因此你實作了 Webhooks。但很快你意識到:如何確保負載是真實的?如果接收方離線怎麼辦?如果沒有適當的防護措施,Webhooks 可能成為安全漏洞和可靠性噩夢。

在本文中,我們將探討 Webhooks 的基本要點,重點關注兩個關鍵方面:用於安全性的簽名負載和用於可靠性的重試機制。我們將提供實用的程式碼範例和最佳實踐,幫助你建置穩健的 Webhook 系統。

什麼是 Webhooks?

Webhooks 是使用者定義的 HTTP 回呼。它們允許一個系統在特定事件發生時,即時將資料推送給另一個系統。與你主動拉取資料的 API 不同,Webhooks 是將資料推送給你。這使得它們非常適合事件驅動的架構。

常見的使用案例包括付款通知(例如 Stripe)、CI/CD 觸發(例如 GitHub)和訊息平台(例如 Slack)。發送方會向接收方提供的 URL 發出 HTTP POST 請求,其中包含事件詳細資訊的負載。

為什麼要用簽名負載保護 Webhooks?

Webhook 端點是公開可存取的,因此容易受到欺騙攻擊。攻擊者可能發送偽造的負載來觸發非預期的動作。為了防止這種情況,發送方使用共享密鑰對負載進行簽名。接收方驗證簽名以確保真實性和完整性。

簽名通常涉及使用密鑰對負載產生 HMAC(基於雜湊的訊息驗證碼)。簽名會放在標頭中(例如 X-Signature)。接收方重新計算 HMAC 並與收到的簽名進行比較。

如何實作簽名負載

讓我們看一個使用 Flask 的 Python 簡單範例。發送方計算簽名:

import hmac
import hashlib
import json
import requests

secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()

headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)

接收方驗證簽名:

from flask import Flask, request, abort
import hmac
import hashlib

app = Flask(__name__)
secret = b'your_shared_secret'

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    body = request.get_data()
    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)
    # Process payload
    return '', 200

最佳實踐:

實作可靠的重試

Webhook 傳遞可能因網路問題、接收方停機或處理錯誤而失敗。穩健的系統應使用指數退避重試失敗的傳遞。

重試策略

常見做法:最多重試 N 次,延遲時間逐漸增加(例如 1 秒、5 秒、30 秒、5 分鐘、30 分鐘)。耗盡重試次數後,將傳遞標記為失敗並發出警報。

以下是使用 requests 函式庫和 tenacity 的 Python 簡單重試機制:

from tenacity import retry, stop_after_attempt, wait_exponential
import requests

@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
    headers = {'X-Signature': signature}
    response = requests.post(url, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return response

重試的最佳實踐:

比較:簽名負載 vs. 基本驗證

方法安全性複雜度重放保護
基本驗證低(每次發送憑證)低否
簽名負載 (HMAC)高中是(含時間戳)

逐步指南:建置帶重試的 Webhook 發送器

  1. 定義事件負載並包含唯一的事件 ID 和時間戳。
  2. 計算簽名,對原始主體使用 HMAC-SHA256。
  3. 發送請求,在標頭中包含簽名。
  4. 處理失敗,使用指數退避重試。
  5. 記錄傳遞並提供可見性。

測試 Webhooks

使用 ngrok 等工具公開你的本機伺服器並測試 Webhook 傳遞。在測試中始終驗證簽名,以便及早發現問題。

常見問題

Webhooks 中的簽名負載是什麼?

簽名負載是發送方使用共享密鑰產生加密簽名(通常為 HMAC)的 Webhook 請求。接收方驗證簽名以確認請求真實且未被篡改。

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

沒有固定次數,但常見做法是使用指數退避重試 3 到 5 次。考慮接收方的典型停機時間和事件的關鍵性。始終允許手動重試。

我可以使用 JWT 進行 Webhook 簽名嗎?

可以,但更複雜。HMAC 簽名更簡單且對大多數情況已足夠。如果你需要包含聲明,JWT 可能合適。

準備好測試你的 Webhook 負載了嗎?使用我們的 JSON Formatter 在發送前驗證和美化你的 JSON 負載。