如何計算 HMAC 簽章

為什麼重要

Webhook 是雲端回呼你的方式。Stripe 在款項入帳時打你的伺服器；GitHub 在 release 建立時通知。為了證明訊息真偽，傳送端會用共用密鑰對 body 計算 HMAC 簽章。若你的驗證器一直不接受簽章，你無法判斷是密鑰錯、演算法錯，還是 body 被代理改過。能並排預覽輸入的 HMAC 工具，可把除錯週期從幾小時縮到幾分鐘。

三個實際場景

操作說明

開啟 HMAC 產生器。

1. 1

   貼上訊息

   被簽署的精確位元組——通常是原始 HTTP body。注意空白差異。

2. 2

   貼上密鑰

   字串預設以 UTF-8 解讀。若廠商給的是二進位鑰，可切換「密鑰為 hex」或「密鑰為 Base64」。

3. 3

   選雜湊演算法

   SHA-256 是現代預設；SHA-1 仍出現在舊系統；SHA-512 較少用但有支援。

4. 4

   選輸出格式

   Hex（小寫）最常見。Base64 是 AWS Sig V4 等少數 API 所需。

5. 5

   與收到的簽章比對

   貼上標頭裡的值。工具會逐字元標示相符與不符。

Message:  t=1731234567.{"id":"evt_123","type":"payment_intent.succeeded"}
Secret:   whsec_abc123xyz
Algorithm: SHA-256

4ed7a40c1e1f9c0bba9d7c1f24eb44a3f0bd06d0c81bd5d4a7f6cf52a6f00f1e

實用技巧

• 先對 body 做 diff。 許多 webhook 失敗來自代理在 body 尾端加了換行。簽章針對精確位元組——多一個尾端換行就差很多。
• 伺服器端務必用常數時間比對。 那是你程式碼的責任，不是簽章工具的。瀏覽器工具可做明文比對，因為沒有資料離開頁面。
• 無停卻輪換密鑰可短暫接受兩把有效鑰。用工具分別算出兩個簽章，確認新鑰可用再汰換舊鑰。
• 把 canonical 字串寫進文件。 AWS Sig V4 等需依特定方式串 method、path、標頭與 body 雜湊；用手動方式在此工具重現一次以確認公式。

常見陷阱

何時不適合用這套

• 公開金鑰簽章（RSA、ECDSA、Ed25519）——需要不同驗證流程。見 如何線上驗證數位簽章。
• 對稱加解密——HMAC 只做認證，不加密。要機密性與真實性並存請用 AES-GCM。
• 密碼儲存——絕不要用 HMAC 存密碼。應用慢速 KDF。

FAQ

下一步

1. 若協定要先對 body 雜湊再 HMAC，可先用 雜湊產生器。
2. 用 參數簽章工具 組完整請求簽章。
3. 解 JWT 簽章可搭配 編碼／解碼工具——JWT 的 HS 演算法使用 HMAC。