Webhooks 解析:簽名載荷與重試機制

Backend2026-11-15TryQuickToolBox

為什麼 Webhooks 在生產環境中會出問題

你已經建立了一個 webhook 端點,在本機測試過,一切運作正常。但到了生產環境:供應商發送了重複的事件、你的端點逾時,或者攻擊者偽造了請求。突然間,你的整合變得不可靠且不安全。

Webhooks 概念上很簡單——由事件觸發的 HTTP 回呼——但生產級實作需要仔細處理安全性和可靠性。本指南涵蓋兩個關鍵面向:用於驗證真實性的簽名載荷,以及處理失敗的重試策略。

什麼是 Webhooks?

Webhook 是一種使用者定義的 HTTP 回呼。當來源系統中發生事件時(例如付款成功),它會向你提供的 URL 發送 HTTP POST 請求,其中包含有關事件的資料。這種推送模式比輪詢更有效率。

但 webhooks 也帶來了挑戰:

讓我們先解決安全性問題。

使用簽名載荷保護 Webhooks

簽名載荷使用共享密鑰對請求主體建立密碼學簽名。發送者將此簽名包含在標頭中(例如 X-Signature)。你的端點重新計算簽名並進行比較。如果它們匹配,則請求是真實的。

HMAC 簽名如何運作

大多數供應商使用 HMAC-SHA256。簽名是使用共享密鑰對原始請求主體計算得出的。流程如下:

  1. 供應商和消費者共享一個密鑰。
  2. 供應商建立載荷,計算 HMAC-SHA256(secret, payload),並將其放在標頭中發送。
  3. 消費者接收請求,讀取原始主體,計算相同的 HMAC,並進行比較。

重要:使用完全按照接收到的原始主體——解析並重新序列化 JSON 可能會改變位元組並破壞簽名。

實作簽名驗證

以下是使用 Express 的 Node.js 範例:

const crypto = require('crypto');
const express = require('express');
const app = express();

// 對 webhook 路由使用原始主體解析器
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');
  
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }
  
  // 處理事件
  const event = JSON.parse(req.body);
  // ... 處理事件
  
  res.status(200).send('OK');
});

始終使用如 crypto.timingSafeEqual 的常數時間比較,以防止時序攻擊。

其他安全考量

實作可靠的重試

即使端點安全,網路問題或暫時性故障也可能導致 webhook 傳遞失敗。穩健的重試機制可確保事件不會遺失。

發送端重試策略

如果你正在建立 webhook 發送器,請實作帶有抖動的指數退避。例如:

加入隨機抖動以避免驚群效應。達到最大嘗試次數後停止並發出警報。

接收端最佳實踐

作為 webhook 消費者,你無法控制發送者的重試策略,但可以讓你的端點更具韌性:

使用冪等性處理重複事件

Webhook 供應商通常會在逾時後重試,因此你可能會多次收到相同的事件。讓你的處理具備冪等性:

使用資料庫唯一索引的範例:

async function handleEvent(event) {
  try {
    await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
  } catch (err) {
    if (err.code === '23505') { // 唯一約束違反
      return; // 已處理過
    }
    throw err;
  }
  // 處理事件
}

比較:Webhook 安全方法

方法 優點 缺點
HMAC 簽名 完整性強,廣泛支援 需要密鑰管理
基本驗證 簡單 安全性較低,憑證在標頭中
IP 允許清單 易於實作 IP 可能變更,不夠穩健

HMAC 簽名是 webhook 安全性的事實標準。

在本機測試 Webhooks

像 ngrok 或 localtunnel 這樣的工具可以將你的本機伺服器暴露到網際網路進行測試。始終使用模擬失敗來測試簽名驗證和重試邏輯。

當檢查來自 webhooks 的 JSON 載荷時,格式化它們有助於除錯。試試我們的 JSON Formatter 來美化列印並驗證 webhook 載荷。

常見問題

如何驗證 webhook 簽名?

使用共享密鑰對原始請求主體計算 HMAC,然後使用常數時間比較函數將其與簽名標頭進行比較。

如果我的 webhook 端點故障該怎麼辦?

大多數供應商會使用指數退避進行重試。確保你的端點快速返回 2xx 並以非同步方式處理,以最小化停機影響。

我可以不使用簽名嗎?

這有風險。沒有簽名,攻擊者可以偽造請求。始終使用簽名載荷,或至少透過 HTTPS 使用基本驗證。

結論

Webhooks 功能強大,但需要關注安全性和可靠性。實作 HMAC 簽名驗證以確保真實性,並設計你的系統以優雅地處理重試和重複事件。透過這些實踐,你的 webhook 整合將變得穩健且適用於生產環境。