HMAC Generator：签名校验排查流程
用 HMAC Generator 排查 webhook 和 API 签名校验失败，逐步确认 secret、原始 payload 字节、canonical string、算法、Base64 或 hex 编码、时间戳、header 解析边界和安全比对顺序，帮助开发者定位签名不匹配、重放保护和日志复现问题。
HMAC 签名失败很难排查，因为错误信息通常很短：signature mismatch、invalid webhook、unauthorized callback。真正原因可能是 secret 选错、payload 字节被改写、算法不同、拼接了 timestamp 前缀，或者 hex/Base64 编码方式不一致。
从精确签名字节开始
使用 HMAC Generator 前，先拿到发送方实际参与签名的原始 payload。这不一定是解析后的 JSON 对象。把 JSON 美化、改变空白、规范化 Unicode，或按不同字段顺序重新序列化，都会改变字节，从而改变签名。
Webhook handler 应在中间件解析前保留 raw request body。API client 应记录安全的 canonical string，例如 method、path、query string、timestamp、body hash，或供应商文档要求的拼接格式。不要凭记忆重建签名输入。
分开确认 secret 和算法
排查要分层。先确认 secret：环境、账号、endpoint 和轮换时间。很多系统会区分 sandbox、production、workspace 和 webhook endpoint secret。再确认算法：HMAC-SHA256 很常见，但也可能是 SHA1、SHA384、SHA512 或自定义 canonical string。
不要同时更换 secret 和算法，否则无法知道哪个因素修复了 mismatch。每次只生成一个候选签名，并和收到的签名对比。
匹配输出编码
同一段 HMAC 字节可以表示成 hex、Base64 或 Base64URL。如果供应商 header 是 `sha256=<hex>`，就和 hex 对比；如果它发送 Base64 字符串，就和 Base64 对比。Base64 Encoder 只能用于表示层编码或解码，不能替代 HMAC。
如果你只需要无 secret 的摘要，应使用 Hash Generator。HMAC 和 hash 相关，但不能互换：HMAC 使用 secret key 验证消息真实性。
建立可复用校验顺序
推荐按这个顺序排查：
- 获取原始 payload 或 canonical string。
- 选择对应环境和 endpoint 的 secret。
- 选择文档指定的 HMAC 算法。
- 用原始输入生成签名。
- 按供应商要求编码输出。
- 去掉 header 前缀后和收到的签名比较。
- 最后再检查 timestamp 容忍窗口、重放保护和 header 解析。
这个顺序可以避免随机试错。如果本地生成的签名已经匹配，但应用仍然拒绝请求，问题更可能在 header 提取、前缀处理、timestamp 解析或 constant-time comparison 代码里。
FAQ
HMAC 和 hash 一样吗？
不一样。hash 对数据做摘要，不需要 secret；HMAC 把 secret key 和 hash function 结合，用于验证消息真实性。
为什么格式化 JSON 会导致 webhook 验签失败？
签名基于字节计算。改变空白、字段顺序或转义方式，即使 JSON 语义相同，也会改变字节。
hex 和 Base64 签名可以直接比较吗？
不能。它们是同一类字节的不同表示。必须先转换成供应商期望的编码形式再比较。
调试时可以分享 webhook payload 吗？
只能在脱敏后分享。移除 secret 和客户数据；只有复现签名问题确实需要时，才保留字节形态特征。