Webhook 驗簽怎麼做(HMAC-SHA256):分步教程與代碼示例
如何用 HMAC-SHA256 驗證 Webhook 簽名:原始請求體、時間戳、常量時間比較、密鑰輪換,以及驗簽失敗最常見的四個原因。
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 可能重複投遞,所以接下來要:
- 在業務狀態變更的同一個事務裏,把事件
id寫入帶唯一約束的表——見 支付回調冪等處理; - 10 秒內返回
2xx,耗時任務交給隊列; - 如果仍有遺漏,從事件接口補回——見 收不到 Webhook 怎麼辦。
總結
- Webhook 驗簽就是重算
HMAC-SHA256(secret, "{t}.{原始請求體}"),並用常量時間與請求頭裏的v1比較; - 拒絕偏差超過 5 分鐘的時間戳;任意一個
v1匹配即接受,因為輪換期間 24 小時內會有兩個; - 對原始字節驗簽,不要對重新序列化的 JSON 驗簽,並使用請求所發往的端點(或應用)在對應環境下的密鑰;
- 上線前用測試回調和驗簽自檢驗證一遍,再按事件
id去重。
在沙箱裏把它跑通
註冊商戶後即可申請測試密鑰,不需要等待資質審核。