金鑰雜湊訊息鑑別碼(HMAC,Keyed-Hash Message Authentication Code)能夠同時證明資料完整性(載荷在傳輸途中未被竄改)與真實性(發送方持有共享金鑰)。要重現服務商的簽章,必須精確匹配三個核心參數:底層雜湊原語、金鑰的原始位元組解碼方式,以及待簽章載荷的精確位元組序列。
範例 1:IETF RFC 2104 / RFC 2202 / RFC 4231 測試案例 2
無論您以 UTF-8 文字 Jefe、原始十六進位 4a656665 還是 Base64 SmVmZQ== 的形式輸入這個 4 位元組金鑰,它都會解碼為完全相同的位元組緩衝區 [0x4a, 0x65, 0x66, 0x65]。對 28 位元組的 UTF-8 訊息 what do ya want for nothing? 進行簽章會得到以下結果:
{
"keyUtf8": "Jefe",
"keyHex": "4a656665",
"keyBase64": "SmVmZQ==",
"message": "what do ya want for nothing?",
"signatures": {
"hmac_md5_hex": "750c783e6ab0b503eaa86e310a5db738",
"hmac_sha1_hex": "effcdf6ae5eb2fa2d27416d5f184df9c259a7c79",
"hmac_sha256_hex": "5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843",
"hmac_sha256_base64": "W9zBRr9gdU5qBCQmCJV1x1oAPwidJzmDnexYuWTsOEM=",
"hmac_sha256_base64url": "W9zBRr9gdU5qBCQmCJV1x1oAPwidJzmDnexYuWTsOEM",
"hmac_sha384_hex": "af45d2e376484031617f78d2b58a6b1b9c7ef464f5a01b47e42ec3736322445e8e2240ca5e69e2c78b3239ecfab21649",
"hmac_sha512_hex": "164b7a7bfcf819e2e395fbe73b56e0a387bd64222e831fd610270cd7ea2505549758bf75c05a994a6d034f65f8f0e6fdcaeab1a34d4a6b4b636e070a38bce737"
}
}
範例 2:Base64 與 Base64URL 的差異及 Webhook 正規化載荷
標準 Base64(RFC 4648 第 4 節)會輸出 +、/ 及結尾的 = 填充字元;而 URL 安全的 Base64URL(RFC 4648 第 5 節,廣泛用於 JWS/JWT 簽章與簽章 URL)則以 - 取代 +、以 _ 取代 /,並省略 = 填充。在 HMAC-SHA256 下使用 UTF-8 金鑰 key 對 The quick brown fox jumps over the lazy dog 進行簽章,可以直觀看到編碼差異:
Key (UTF-8): key
Message (UTF-8): The quick brown fox jumps over the lazy dog
HMAC-SHA256 Hex: f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
HMAC-SHA256 Base64: 97yD9DBThCSxMpjmqm+xQ+9NWaFJRhdZl0edvC0aPNg=
HMAC-SHA256 Base64URL: 97yD9DBThCSxMpjmqm-xQ-9NWaFJRhdZl0edvC0aPNg
在驗證正式環境的 Webhook 標頭時,請先依照各服務商的規範建構精確的待簽章載荷,然後再去除標頭中的前綴進行比對:
GitHub (X-Hub-Signature-256: sha256=<hex>):
Signed input = <raw_http_body>
Stripe (Stripe-Signature: t=1730419200,v1=<hex>):
Signed input = 1730419200.<raw_http_body>
Slack (X-Slack-Signature: v0=<hex>):
Signed input = v0:1730419200:<raw_http_body>
Shopify (X-Shopify-Hmac-Sha256: <base64>):
Signed input = <raw_http_body>