Shopify Webhook HMAC 校验失败怎么办

现象#

HMAC 校验总失败。日志里密钥正确，却对不上。常见于框架已把 raw body 解析成对象后再 JSON.stringify 去算签名。

原因#

Shopify HMAC 必须对 原始请求字节计算。任何改写空格、键序、编码的再序列化都会失败。读错头字段名（X-Shopify-Hmac-Sha256）或用错密钥（API 密钥 vs 应用密钥）同样失败。

步骤#

1. 中间件保留 raw body（如 Buffer），先验签再 JSON.parse。
2. 用官方示例向量或 Shopify 文档中的校验算法核对。
3. 确认密钥来自应用共享密钥。
4. 禁止日志打印完整 raw body（含 PII），只记是否通过。
5. 参见 shopify.dev Webhook 验证章节。
6. 对失败请求返回非 2xx 以便 Shopify 重试（注意幂等）。

验收#

官方测试投递与真实订单验签均通过；再序列化路径有单元测试覆盖。