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
验证有两条路:
- 回发验证(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。 - 自校验:拉证书本地验签,无外网依赖,也可以用自己生成的密钥对做离线单测。
下面都按自校验这条路走。
第一步: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-idtimeStamp来自paypal-transmission-timewebhookId是“订阅了这个 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