Webhooks 詳解:簽名負載與重試機制
你已經建置了一個 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
最佳實踐:
- 使用強密鑰並定期輪換。
- 在簽名資料中包含時間戳以防止重放攻擊。
- 使用
hmac.compare_digest進行常數時間比較。 - 對原始主體進行簽名,而不是解析後的 JSON,以避免不一致。
實作可靠的重試
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 發送器
- 定義事件負載並包含唯一的事件 ID 和時間戳。
- 計算簽名,對原始主體使用 HMAC-SHA256。
- 發送請求,在標頭中包含簽名。
- 處理失敗,使用指數退避重試。
- 記錄傳遞並提供可見性。
測試 Webhooks
使用 ngrok 等工具公開你的本機伺服器並測試 Webhook 傳遞。在測試中始終驗證簽名,以便及早發現問題。
常見問題
Webhooks 中的簽名負載是什麼?
簽名負載是發送方使用共享密鑰產生加密簽名(通常為 HMAC)的 Webhook 請求。接收方驗證簽名以確認請求真實且未被篡改。
失敗的 Webhook 應該重試多少次?
沒有固定次數,但常見做法是使用指數退避重試 3 到 5 次。考慮接收方的典型停機時間和事件的關鍵性。始終允許手動重試。
我可以使用 JWT 進行 Webhook 簽名嗎?
可以,但更複雜。HMAC 簽名更簡單且對大多數情況已足夠。如果你需要包含聲明,JWT 可能合適。
準備好測試你的 Webhook 負載了嗎?使用我們的 JSON Formatter 在發送前驗證和美化你的 JSON 負載。