代码 PayPal webhook 验签总失败:签名串第三段是 webhook ID 不是 event ID,crc32 还得是无符号十进制

2026-11-17 09:01:13

PayPal webhook 验签本地永远 FAILURE:先用 openssl 把签名串复现出来

前提:PayPal 不使用共享密钥

PayPal webhook 验签与 Stripe 的 whsec 不是一套机制。它用 PayPal 自己的私钥对每个请求做 RSA-SHA256 签名,公钥通过请求头里的 paypal-cert-url 现场下发。照搬 HMAC 共享密钥的校验思路,本地必然一直 FAILURE。

请求头一共五个:

  • paypal-transmission-id:本次投递的唯一 ID(UUID 形式)
  • paypal-transmission-time:ISO 8601 时间戳
  • paypal-transmission-sig:base64 编码的 RSA-SHA256 签名
  • paypal-cert-url:PEM 证书地址,域名必须在 paypal.com 或其子域
  • paypal-auth-algo:目前只见过 SHA256withRSA

验证有两条路:

  1. 回发验证(postback):POST https://api-m.paypal.com/v1/notifications/verify-webhook-signature,沙箱用 api-m.sandbox.paypal.com。Header 带 Bearer OAuth token,body 传 transmission_id / transmission_time / cert_url / auth_algo / transmission_sig / webhook_id / webhook_event(原始 JSON 对象)。返回 {"verification_status":"SUCCESS"},非 SUCCESS 一律拒绝。缺点是每个 webhook 多一次外网往返,还要维护 OAuth token。并且 Webhooks simulator 发出的测试事件不支持 postback 验证,本地拿模拟事件测永远 FAILURE。
  2. 自校验:拉证书本地验签,无外网依赖,也可以用自己生成的密钥对做离线单测。

下面都按自校验这条路走。

第一步:openssl 手工复现,把代码问题和数据问题分开

不要先在代码里猜。导出三个值到 shell:

TID=...
TIME=...
WEBHOOK_ID=...
# body 原样存成 raw.json

CRC=$(python3 -c "import zlib,sys;print(zlib.crc32(open('raw.json','rb').read())&0xffffffff)")
printf '%s|%s|%s|%s' "$TID" "$TIME" "$WEBHOOK_ID" "$CRC" > msg.txt

curl -sS "$CERT_URL" -o cert.pem   # 先校验过域名再 curl
echo "$SIG" | base64 -d > sig.bin

openssl dgst -sha256 -verify cert.pem -signature sig.bin msg.txt

输出 Verified OK 还是 Verification failure,这一步就能区分两类问题:

  • openssl 也失败 → 签名串拼错了,或者 body 不是原始字节
  • openssl 成功 → 数据没问题,是代码里取 body / 拼串的方式错了

第二步:签名串四段,第三段最容易填错

官方原文格式:

transmissionId | timeStamp | webhookId | crc32

用 | 分隔,四段含义:

  • transmissionId 来自 paypal-transmission-id
  • timeStamp 来自 paypal-transmission-time
  • webhookId 是“订阅了这个 listener URL 的 webhook 的 ID”,不是 event.id,也不在请求里,要去开发者后台 Application → Webhooks 复制
  • crc32 是 HTTP body 原始字节的 CRC32,十进制无符号整数

示例:

db49fb10-1343-11ef-ac58-e32457403f67|2024-05-16T05:19:23Z|0NH55953DH663215D|2904282587

按踩坑频率排,第一条就是:第三段填了 event.id(WH-3F56...)而不是 webhook ID。串不同,签名对不上,必然 FAILURE。

其他几条同样致命:

  • 沙箱 webhook ID 用在生产(或反之),签名串不同,FAILURE。
  • 算法名照抄:paypal-auth-algo 是 SHA256withRSA,PHP 的 openssl_verify 传 'sha256withRSA' 会失败(openssl 要 sha256WithRSAEncryption),直接传 OPENSSL_ALGO_SHA256 或 'sha256' 最省事。
  • 证书缓存:cert-url 每次都是一个 URL,PayPal 轮换证书是换 URL,所以按 URL 永久缓存即可,不用每次下载;但缓存之后也不能跳过域名校验。
  • 校验了签名却没校验 cert-url 域名:把请求头里的 URL 直接 curl,等于让攻击者给你他自己的证书,签名当然“通过”。必须校验 host 等于 paypal.com 或以 .paypal.com 结尾。
  • 内网 / CDN 把 POST 转成 GET,或者 301 跳到 https:PayPal 侧会当作投递失败。

第三步:body 必须取原始字节

crc32 算的是 HTTP body 的原始字节。框架解析后重新序列化,就会改变空格和键序:

  • JSON.stringify(req.body)
  • PHP 里用 $_POST,或者 json_encode(json_decode($raw))

这些写法都会让 crc32 变化,签名不匹配。正确取法:

  • PHP:php://input
  • Laravel:$request->getContent()
  • Express:express.raw()
  • FastAPI:await request.body()
  • Go:io.ReadAll(r.Body)

CRC32 的输出形态也要对。PayPal 要十进制无符号:

  • Node 22 的 zlib.crc32 直接返回无符号
  • Python zlib.crc32 要 & 0xFFFFFFFF
  • PHP 64 位下 crc32() 返回正数,32 位构建会溢出成负数,用 sprintf('%u', crc32($body))
  • 有些库返回带符号 int32(如 -662733300),拼进串就错

投递与重试:验签失败不要回 4xx

listener 必须是 HTTPS 443,每次都要回 2xx(200、201 都行)。非 2xx 或连不上就重试:3 天内最多 25 次,仍失败标记 Failed。后台 Webhook Events 可以手动 resend;每个事件 body 的 links 数组里有 rel=resend 的链接,也可以调 POST /v1/notifications/webhooks-events/{event_id}/resend 重放。

所以验签失败不要回 4xx,会白烧 25 次重试配额。正确做法是回 200 后落库标记 rejected,报警人工看。反过来说,业务处理异常也不能回 500 —— 先把原始 body 存下来,再异步处理。

去重键用 event.id(WH-...),别用 transmission-id(有资料称重试时不变,未实测)。

语言片段

PHP:

$raw = file_get_contents('php://input');
$crc = sprintf('%u', crc32($raw));
$msg = $headers['paypal-transmission-id'].'|'.$headers['paypal-transmission-time'].'|'.$webhookId.'|'.$crc;
$ok = openssl_verify($msg, base64_decode($headers['paypal-transmission-sig']), $pem, OPENSSL_ALGO_SHA256) === 1;
// 注意:签名是对 $msg 的字节签名,不要加换行

Go:

sum := crc32.ChecksumIEEE([]byte(rawBody))
msg := fmt.Sprintf("%s|%s|%s|%d", tid, ttime, webhookID, sum)

Node:

const crc = zlib.crc32(rawBody); // Node >= 22,返回无符号

遗留 IPN 是另一套

老 IPN 不能和 webhook 混着排查:要把收到的 body 原样再 POST 回 https://ipnpb.paypal.com/cgi-bin/webscr(沙箱 ipnpb.sandbox.paypal.com),末尾追加 &cmd=_notify-validate,然后看返回是不是 VERIFIED。带中文或多字节内容要加 charset=utf-8,否则回传时编码不一致会拿到 INVALID。新项目别用 IPN。

上线检查

  • 沙箱和生产的 listener、client_id/secret、webhook_id 全部分开
  • WAF / 防盗链别拦 POST,别要求 UA 或 Referer
  • 对 listener 的 4xx / 5xx 率做告警,重试配额烧完就是永久丢单
  • 验签失败日志必须有:event.id、transmission-id、body 的 sha256、cert-url、失败原因分类

参考链接

  • 官方 Integration:https://developer.paypal.com/api/rest/webhooks/rest/
  • 官方 Webhooks overview:https://developer.paypal.com/api/rest/webhooks
复制全文 生成海报 PayPal Webhook 验签 RSA 支付对接 排障

推荐文章

程序员茄子在线接单