Webhook 詳解:簽章載荷與可靠重試

Backend2026-11-11TryQuickToolBox

你發布了支付整合功能,在預備環境中一切正常。但到了生產環境,一位客戶完成付款,你的端點卻逾時兩秒,訂單始終沒有啟用。同時,支付供應商對同一個事件重試了三次,而你的應用程式為那個成功的事件建立了三筆重複訂單。Webhook 看起來很簡單——不過是一個 HTTP POST——但真正困難的部分在於信任與交付保證。

本文探討最常導致 Webhook 整合失敗的兩件事:驗證請求確實來自發送方,以及處理重試時不產生重複的副作用。

Webhook 究竟是什麼

Webhook 是一種反向 API 呼叫。與其讓你的伺服器每分鐘輪詢供應商詢問「有什麼新消息嗎?」,不如由供應商在事件發生時,主動推送 HTTP 請求到你註冊的 URL。載荷通常是 JSON,事件類型則位於請求主體或標頭中。

POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592

{
  "id": "evt_8f2c1a",
  "type": "payment.succeeded",
  "created": 1735689600,
  "data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}

發送方有兩個設計決策很重要,評估任何供應商時都應檢查這兩點:它是否對載荷簽章?它是否在失敗時重試?

未簽章 Webhook 的危險

你的 Webhook URL 是公開的。任何知道這個 URL 的人都可以 POST 一個偽造的 payment.succeeded 事件,將未付款的訂單標記為已付款。IP 允許清單有一點幫助,但供應商會更換 IP、運行於 CDN 之後,而且你可能拿不到穩定的清單。

穩健的解決方案是使用只有你和供應商知道的共享密鑰,對原始請求主體進行 HMAC 簽章。供應商計算簽章並在標頭中發送;你重新計算並比對。

正確驗證簽章

有三個細節很容易出錯:

// Node.js / Express 範例
const crypto = require('crypto');

function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('='))
  );
  const timestamp = Number(parts.t);
  if (!timestamp) return false;

  // 拒絕過期請求(重放防護)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // ... 處理事件
  res.status(200).send('ok');
});

注意 express.raw() 中介軟體。如果你在此路由之前掛載了 express.json(),主體已經被解析,簽章檢查會無聲地失敗——這是非常常見的錯誤。

設計不遺失事件的重試機制

Webhook 交付是「至少一次」,而非「恰好一次」。網路會故障,你的部署會重啟容器,供應商無從得知你的 200 回應是否真實。因此供應商會以指數退避重試,通常持續數小時或數天。

快速回應,稍後處理

你的端點應做最少的事:驗證、持久化原始事件、回傳 2xx。繁重的工作——發送電子郵件、呼叫其他 API、產生發票——應在背景任務中進行。若處理時間超過供應商的逾時限制,請求會被視為失敗並重試,即使你已完成工作。

  1. 驗證簽章與時間戳。
  2. 將事件插入資料表,並對事件 ID 設定唯一約束。
  3. 立即回傳 200。
  4. 非同步處理已儲存的事件,並標記為完成。

冪等性:解決重複問題的真正方法

由於重試會發生,你的處理程序必須能安全地執行兩次。事件 ID 是天然的冪等鍵。

INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;

若插入影響零行,表示你已見過此事件——確認並繼續。對於業務邏輯,套用相同概念:啟用付款時使用訂單 ID 作為唯一鍵,這樣第二個事件就無法建立第二次啟用。

刻意選擇狀態碼

狀態碼供應商行為使用時機
200 / 204標記為已交付事件已接受(即使已處理過)
400通常不重試格式錯誤且永遠無法處理的載荷
401通常不重試簽章不符——檢查你的密鑰
429以退避重試你正在進行速率限制
500 / 503以退避重試暫時性失敗、資料庫故障、部署進行中

對無法儲存的事件回傳 200 是最糟的選擇:供應商停止重試,事件永遠消失。回傳 5xx,讓重試發揮作用。

生產環境實用檢查清單

在本機測試 Webhook

你無法輕易在 localhost 上接收公開的 POST。選項包括:暴露開發連接埠的通道工具、供應商的 CLI(若有),或一個小型腳本向你的處理程序發送簽章載荷,以便你演練驗證路徑。

最有價值的測試是重複事件:發送同一個事件兩次,確認你的系統最終狀態相同。然後發送一個帶有舊時間戳的事件,確認它被拒絕。再篡改主體的一個位元組,確認簽章檢查失敗。

除錯載荷

Webhook 主體是 JSON,格式錯誤或深度嵌套的載荷在日誌中很難閱讀。格式化工具能幫助你在撰寫解析程式碼之前快速檢視結構。JSON 格式化工具 在瀏覽器中執行,因此你可以貼上擷取的載荷,而不會將客戶資料傳送到伺服器。

常見問題

Webhook 與 API 有何不同?

API 是拉取式:你的程式碼在需要資料時呼叫供應商。Webhook 是推送式:供應商在事件發生時呼叫你的端點。大多數整合兩者並用——Webhook 用於事件通知,API 用於取得完整詳細資訊或執行操作。

為何我的 HMAC 簽章永遠不符?

常見原因是對重新序列化的主體簽章,而非原始位元組。空白、鍵順序與 Unicode 轉義都會改變雜湊值。在任何 JSON 中介軟體之前讀取原始請求主體,並確認密鑰與雜湊演算法符合供應商文件。

Webhook 重試有保證嗎?

沒有。供應商通常會在有限視窗內以指數退避重試,然後放棄。將 Webhook 視為快速通知管道,而非真實來源:定期與供應商的 API 對帳,讓遺漏的事件最終得到修正。

如果你今天正在建立或除錯 Webhook 接收器,請先鎖定簽章驗證與冪等儲存——這兩項變更就能消除現實世界中大多數的 Webhook 事故。