Webhook签名不匹配问题：前端请求失败，Postman及公共平台正常

以下是导致前端计算的HMAC-SHA256+Base64签名和Postman/第三方平台不一致的核心原因：

• JSON序列化规则不一致
  这是最常见的问题：前端JSON.stringify的输出和Zum Rails API使用的序列化逻辑可能存在差异：

  • 键的排序：很多后端会对JSON的键按字母顺序排序后再计算签名，但原生JSON.stringify默认不会排序键。如果API要求排序，前端没做这一步，签名必然不匹配。
  • 空白字符：Postman这类工具可能会自动格式化JSON（添加空格、换行），而JSON.stringify默认输出紧凑格式；或者前端代码中不小心给字符串加了多余的空格、换行符，导致负载内容和后端预期不符。
  • 特殊值处理：比如JSON.stringify会把undefined、NaN转成null，如果后端用的序列化工具对这些值的处理逻辑不同，也会导致内容差异。

• UTF-8编码细节问题
  前端在将字符串转成UTF-8字节流时可能出现偏差：

  • 直接使用字符串计算HMAC时，部分浏览器的字符编码处理和后端不一致。建议改用TextEncoder将JSON字符串转成Uint8Array后再计算HMAC，确保编码和后端完全一致。
  • 检查是否引入了UTF-8 BOM（字节顺序标记）：如果前端生成的字符串带BOM，而后端未处理，会直接导致签名不匹配。

• 请求发送时的负载篡改
  前端发送请求的过程中，负载可能被意外修改：

  • 使用fetch或axios时，如果错误设置了请求头或序列化逻辑，可能导致实际发送的请求体和你计算签名用的JSON.stringify结果不一致。比如重复序列化JSON，或者Content-Type未正确设置为application/json导致工具自动转换格式。
  • 浏览器的调试工具、代理扩展可能会修改请求体内容，干扰签名验证。可以尝试关闭所有扩展后再测试。

• 密钥处理错误
  确认前端使用的签名密钥和Postman/平台完全一致：检查是否有多余的空格、换行符，或者密钥是Base64编码的情况下，前端是否正确解码成原始字节再用于HMAC计算。

1. 把前端计算签名用的JSON字符串、Postman发送的JSON内容复制到文本对比工具中，逐字符对比是否完全一致。
2. 在浏览器网络面板中查看实际发送的请求体，和前端代码中用于计算签名的字符串做对比，确认两者没有差异。
3. 按照Zum Rails API文档要求的序列化规则（比如排序键）手动处理JSON，再重新计算签名验证是否匹配。

内容的提问来源于stack exchange，提问作者Gabriel Temitope