跳轉到主要內容

Webhook 驗簽怎麼做(HMAC-SHA256):分步教程與代碼示例

如何用 HMAC-SHA256 驗證 Webhook 簽名:原始請求體、時間戳、常量時間比較、密鑰輪換,以及驗簽失敗最常見的四個原因。

發佈於 約 4 分鐘閲讀

手繪插畫:一個帶 t= 和 v1= 簽名頭的 Webhook 請求,經過 HMAC-SHA256 校驗後得到一個勾,旁邊一個人正指着它
本文目錄
  1. Webhook 簽名裏有什麼?
  2. Webhook 驗簽的步驟
  3. Webhook 驗簽代碼示例
  4. Webhook 驗簽為什麼會失敗
  5. 如何測試 Webhook 驗簽
  6. 驗簽之後:Webhook 處理還要做什麼
  7. 總結

Webhook 驗簽,就是用你的簽名密鑰對請求計算一次 HMAC-SHA256,再和發送方放在請求頭裏的簽名比較。一致,説明請求來自持有密鑰的一方,而且請求體在路上沒有被改過;不一致,就拒絕它。正是 Webhook 簽名驗證,讓知道你回調地址的人沒法偽造一條"支付成功"推給你。

這篇文章一步步説明如何驗證 KukoPay 的 Webhook 簽名,附 Node.js 和 Python 代碼,並講清楚幾乎所有驗簽失敗背後的四個原因:請求體被重新序列化、用錯了密鑰、輪換期間丟了第二個簽名、服務器時鐘偏差。

Webhook 簽名裏有什麼?

KukoPay 發出的每一條 Webhook 都帶有這個請求頭:

X-KukoPay-Signature: t=1758268800,v1=9c1f...
  • t 是簽名時的 Unix 時間戳(秒);
  • v1 是 HMAC-SHA256(secret, "{t}.{原始請求體}") 的十六進制結果。

時間戳和請求體一起簽名,舊請求就沒法拿來重放:改了時間戳,簽名就對不上;不改,你的接收端一看就知道它太舊了。

Webhook 驗簽的步驟

讀取原始請求體

就是收到的原始字節,在任何 JSON 解析之前。

解析請求頭

取出 t,並收集全部 v1= 的值——可能不止一個。

檢查時間戳

t 與你的服務器時間相差超過 300 秒(5 分鐘)就拒絕。

計算預期簽名

用簽名密鑰對 {t}.{原始請求體} 計算 HMAC-SHA256,取小寫十六進制。

常量時間比較

任意一個 v1 匹配即接受;否則返回錯誤,不做任何處理。

Webhook 驗簽代碼示例

import crypto from "crypto"
 
export function verifyKukoPay(rawBody, signatureHeader, secret) {
  const parts = signatureHeader.split(",").map((item) => {
    const index = item.indexOf("=")
    return [item.slice(0, index).trim(), item.slice(index + 1).trim()]
  })
  const timestamp = parts.find(([key]) => key === "t")?.[1]
  const received = parts.filter(([key]) => key === "v1").map(([, value]) => value)
  if (!timestamp || received.length === 0) return false
 
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
 
  const expected = Buffer.from(
    crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex")
  )
  return received.some((candidate) => {
    const buffer = Buffer.from(candidate)
    return buffer.length === expected.length && crypto.timingSafeEqual(buffer, expected)
  })
}
import hashlib, hmac, time
 
def verify_kukopay(raw_body: bytes, signature_header: str, secret: str) -> bool:
    timestamp, received = None, []
    for item in signature_header.split(","):
        key, _, value = item.strip().partition("=")
        if key == "t":
            timestamp = value
        elif key == "v1":
            received.append(value)
    if not timestamp or not received:
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, candidate) for candidate in received)

PHP 版本,以及完整的請求頭和事件類型,見 Webhook 文檔。

Webhook 驗簽為什麼會失敗

請求體被解析後又重新序列化

這是最常見的原因。很多框架在你的處理函數執行前就解析了 JSON,再序列化回去,空格或字段順序一變,HMAC 就對不上了,哪怕內容"一樣"。請對原始字節驗簽。以 Express 為例,給回調路由用 express.raw({ type: "application/json" }) 而不是 express.json(),驗簽通過後再解析 JSON。

用錯了簽名密鑰

每個簽名密鑰只屬於一個地方:

  • Webhook 端點有自己的密鑰,只在創建端點或輪換密鑰時顯示一次;
  • 訂單自帶的 notify_url 用應用的回調簽名密鑰簽名,在 開發者 → API 密鑰 頁面簽發;
  • 沙箱和正式環境各自獨立:沙箱密鑰永遠驗不過正式環境的 Webhook。

如果你有多個端點或多個應用,確認接收端用的是請求所發往端點的密鑰——X-KukoPay-Endpoint-Id 請求頭會告訴你是哪個。見 如何管理多個 Webhook 端點。

只保留了最後一個簽名

輪換密鑰後,舊密鑰會和新密鑰一起簽名 24 小時,請求頭裏會出現兩個 v1=。把請求頭轉成 map 的寫法(Object.fromEntries、字典)只會留下其中一個,整個窗口期內,還沒切換的一方會全部驗簽失敗。請收集所有 v1,任意一個匹配即可。輪換本身見 如何輪換 Webhook 密鑰。

服務器時鐘不準

時鐘偏差超過 5 分鐘的服務器,會把真實的 Webhook 當作過期請求拒絕。請保持時間同步(NTP),並記錄被拒時間戳的偏差,這樣時鐘漂移能很快被發現。

如何測試 Webhook 驗簽

不需要真的付款,也能確認驗簽寫對了:

  • 在 開發者 → 沙箱聯調 中發送測試回調。它和真實回調的構造、簽名完全相同,頁面會同時顯示我們發出的請求和你的接口返回的內容。測試回調帶 "test": true,id 以 evt_test_ 開頭——收到時不要發貨。
  • 在 開發者 → Webhook 頁面使用驗簽自檢:粘貼原始請求體和 X-KukoPay-Signature,後台會在你的瀏覽器裏重算簽名,告訴你問題出在密鑰、請求體被重新格式化,還是時間戳。
  • 對沙箱訂單模擬支付結果,就能收到一條真實的 payment.succeeded,按正式規則簽名和重試。見 沙箱與正式環境的區別。

驗簽之後:Webhook 處理還要做什麼

簽名有效只能證明是誰發的,不能證明你沒處理過它。Webhook 可能重複投遞,所以接下來要:

  1. 在業務狀態變更的同一個事務裏,把事件 id 寫入帶唯一約束的表——見 支付回調冪等處理;
  2. 10 秒內返回 2xx,耗時任務交給隊列;
  3. 如果仍有遺漏,從事件接口補回——見 收不到 Webhook 怎麼辦。

總結

  • Webhook 驗簽就是重算 HMAC-SHA256(secret, "{t}.{原始請求體}"),並用常量時間與請求頭裏的 v1 比較;
  • 拒絕偏差超過 5 分鐘的時間戳;任意一個 v1 匹配即接受,因為輪換期間 24 小時內會有兩個;
  • 對原始字節驗簽,不要對重新序列化的 JSON 驗簽,並使用請求所發往的端點(或應用)在對應環境下的密鑰;
  • 上線前用測試回調和驗簽自檢驗證一遍,再按事件 id 去重。

在沙箱裏把它跑通

註冊商戶後即可申請測試密鑰,不需要等待資質審核。