Node.js中PayPal Webhook签名验证失败的调试咨询

一、原始报文处理与消息构建的常见陷阱 #

• 请求体被无意识修改：必须确保express.raw()是第一个处理请求的中间件，避免任何中间件（如express.json()、压缩中间件）对请求体做转码、截断或格式化操作。哪怕是微小的修改（比如自动添加空格）都会导致签名不匹配。
• 拼接顺序完全不能错：严格按照传输ID（Paypal-Transmission-Id） + 传输时间（Paypal-Transmission-Time） + Webhook ID（Paypal-Webhook-Id） + 原始报文的顺序拼接，颠倒或遗漏任一字段直接验证失败。
• 字段值必须原样取用：传输时间要直接取请求头的原始ISO 8601字符串，不能做格式化；传输ID、Webhook ID也不能做trim()或大小写转换，完全保留原始值。
• 遗漏报文的二进制细节：不要将原始Buffer转成字符串后再拼接，直接用Buffer拼接所有字段，避免字符串转码过程中丢失二进制信息。

二、换行符标准化要求 #

必须标准化换行符。PayPal发送的原始报文使用LF（\n）换行，若你的服务器接收时自动转为CRLF（\r\n），或处理时手动修改了换行符，会导致报文哈希不一致。
处理方案：将原始报文中的所有\r\n替换为\n，或直接基于原始Buffer处理，避免字符串层面的换行符转换。

三、UTF-8编码的细节问题 #

• 严格使用UTF-8编码：确保请求体始终以UTF-8编码处理，禁止转成其他编码（如GBK）再转回，否则会导致字节流变化。
• 剔除UTF-8 BOM：检查原始请求体开头是否存在BOM（字节EF BB BF），若有必须剔除——PayPal发送的报文不含BOM，保留会导致哈希错误。
• 直接操作Buffer：在Node.js中优先用Buffer处理原始请求体，避免toString('utf8')这类可能修改字节的操作，确保和PayPal发送的字节完全一致。

四、调试技巧与工具 #

• 字节级对比原始报文：将接收到的原始请求体保存为本地文件，再用PayPal Webhook模拟器发送测试请求并保存其报文，用diff命令（Linux/macOS）或WinMerge（Windows）做字节对比，找出差异点。
• 对比哈希值定位问题：分别计算你构建的验证消息的哈希，以及解密签名得到的PayPal哈希，看是否一致：

  const crypto = require('crypto');
  // 构建验证消息（用Buffer拼接避免编码问题）
  const verificationBuffer = Buffer.concat([
    Buffer.from(transmissionId),
    Buffer.from(transmissionTime),
    Buffer.from(webhookId),
    rawBody // 原始请求体Buffer
  ]);
  // 计算本地哈希
  const localHash = crypto.createHash('sha256').update(verificationBuffer).digest('hex');
  // 解密PayPal签名得到其哈希
  const decodedSignature = crypto.publicDecrypt(pemCertificate, Buffer.from(signature, 'base64')).toString('hex');
  console.log('本地哈希:', localHash);
  console.log('PayPal哈希:', decodedSignature);
  

• 验证PEM证书有效性：检查证书格式是否正确，避免缺少首尾标记或换行错误：

  try {
    const publicKey = crypto.createPublicKey(pemCertificate);
    console.log('证书格式有效');
  } catch (err) {
    console.error('证书无效:', err.message);
  }
  

• 用PayPal官方工具交叉验证：在PayPal开发者后台的Webhook详情页，使用官方签名验证工具，输入测试请求的签名、传输ID、时间、Webhook ID和报文，若官方工具能通过但你的代码不能，说明代码的消息构建或报文处理有误；若官方也不能通过，可能是请求接收环节出了问题。

内容的提问来源于stack exchange，提问作者Gurpreet Kaur