通知收到了、200 也回了,用户订阅没续期:Apple V2 通知排障笔记
现象很具体:Apple 的 V2 通知已经 POST 到我们的 HTTPS 回调,服务端返回 200,日志里 signedPayload 也解出了 JSON,但用户的订阅状态没变、续期没入账。返回 200 只说明「我收到了」,不说明「我验对了、也算对了」。下面按实际排查顺序记一遍。
官方字段说明:signedPayload。参考实现:apple-signature-tutorial。Node 官方库:apple/app-store-server-library。
一、先把 JWS 的三段拆清楚
signedPayload 是一个 JWS 字符串,三段 Base64URL 用句点分隔:header、payload、signature。
- 解 payload 得到
responseBodyV2DecodedPayload,业务字段都在这里; - 解 header 得到
JWSDecodedHeader,验签用的x5c证书链在 header 里,不在 payload 里。
V1 通知和 notification_type 字段已弃用,应实现 V2 endpoint。另外注意嵌套:V2 response body 含 signedPayload,部分通知还带 data 对象,其中 transaction 与 subscription renewal 的信息同样是 App Store 用 JWS 签名的,即第二层 JWS:signedTransactionInfo、signedRenewalInfo。App Store Server API 与 StoreKit 用的是同一套 JWS 格式,验签逻辑可以复用。
通知通过 HTTP POST 到开发者配置的 HTTPS URL,需要返回 HTTP 状态码表明接收结果。这一步只是「应答」,不是「处理完成」。
二、x5c 是三条证书,不是一条
x5c 必须是长度为 3 的数组:leaf、intermediate、root。要做完这几件事:
- leaf 由 intermediate 签发;
- intermediate 由 root 签发;
- root 必须是 Apple 的;
- 三者都不能过期;
- leaf 与 intermediate 必须是 App Store 用途的证书。
第 5 条最容易漏。同一个 Apple Root 下还签发了其他用途的证书(包括发给开发者的),如果不检查用途,用那种证书拼出来的链同样能「通过」密码学校验。App Store 证书靠两个扩展 OID 识别:
- leaf:
1.2.840.113635.100.6.11.1 - intermediate:
1.2.840.113635.100.6.2.1
intermediate 还要有 CA:TRUE。
三、签名材料必须是线上原始串
验签的输入是 signingInput:header 与 payload 的原始 Base64URL 串以点连接,即 header.payload,不能解码成 JSON 再重新编码。空格、转义斜杠、空对象的编码方式都可能变化,重新序列化后签名就对不上——这类失败看起来像「证书有问题」,实际是材料变了。
四、根证书钉指纹,leaf 和 intermediate 不要存
根证书不需要下载文件,钉 SHA-256 指纹就够。Apple Root CA - G3(当前 2039 年到期)的指纹校验命令:
curl -s https://www.apple.com/certificateauthority/AppleRootCA-G3.cer | openssl x509 -inform DER -noout -fingerprint -sha256
代码里存常量:
const APPLE_ROOT_CA_G3_SHA256 = '63343abfb89a6a03ebb57e9b3f5fa7be7c4f5c756f3017b3a8c488c3653e9179';
只有 root 是固定的;leaf 与 intermediate 每次通知随 x5c 下发,不定期轮换,靠签名关系和 OID 识别,不需要存。
五、PHP 侧的两个坑
第一个是返回值语义。openssl_x509_verify 返回 1 表示签名有效、0 表示无效、-1 表示出错。必须与 1 严格比较:
// 错:-1(出错)会被当成真值放过去
if (!openssl_x509_verify($cert, $issuerCert)) { /* ... */ }
// 对
if (openssl_x509_verify($cert, $issuerCert) !== 1) { /* 拒绝 */ }
第二个是签名格式。用 leaf 的公钥对 signingInput 验 ES256。JWS 里的 ES256 签名是 r、s 两个 32 字节整数直接拼接(共 64 字节),而 OpenSSL 需要 ASN.1 DER SEQUENCE,中间要做一次编码转换(先 ltrim 去掉前导 0x00,首字节 > 0x7f 时补一个 0x00 保持正整数,再拼成 30 len 02 len r 02 len s)。这一步属于编码层细节,另有专文,这里只作必要步骤带过。
验签主流程的形状:
$parts = explode('.', $signedPayload);
[$b64Header, $b64Payload, $b64Signature] = $parts;
// 必须是原始串,不能 json_decode 后重新编码
$signingInput = $b64Header . '.' . $b64Payload;
$header = json_decode(base64_decode(strtr($b64Header, '-_', '+/')), true);
$x5c = $header['x5c'] ?? [];
if (count($x5c) !== 3) {
// 链长度不对,直接拒绝
}
$leaf = x509_from_der($x5c[0]);
$intermediate = x509_from_der($x5c[1]);
$root = x509_from_der($x5c[2]);
if (openssl_x509_verify($leaf, $intermediate) !== 1) { /* 拒绝 */ }
if (openssl_x509_verify($intermediate, $root) !== 1) { /* 拒绝 */ }
// 再比对 root 的 SHA-256 指纹、三者有效期、两个 OID、intermediate 的 CA:TRUE
$ok = openssl_verify(
$signingInput,
der_from_jws_signature($b64Signature), // r||s -> ASN.1 DER,细节另文
openssl_pkey_get_public($leaf),
OPENSSL_ALGO_SHA256
);
if ($ok !== 1) { /* 拒绝 */ }
六、密码学过了,还要比 bundleId 和 environment
Apple 用同一套证书给所有 app 签通知。一条真实、签名完全合法、但发给别的 app 的通知,能通过上面全部密码学校验。所以验完签名必须比对 bundleId。
四个载体互斥出现,取详情按 data ?? summary ?? externalPurchaseToken ?? appData 的顺序取,然后和本地配置比对,不等就 log 并返回 422。注意 TEST 类通知没有 signedTransactionInfo,不能假设一定有交易。
Node 官方库把这件事包进了 verifyAndDecodeNotification,构造函数是:
(appleRootCertificates: Buffer[], enableOnlineChecks, environment, bundleId, appAppleId?)
源码里的校验分支:
x5c长度 != 3 →INVALID_CHAIN_LENGTHbundleId不匹配,或生产环境appAppleId不匹配 →INVALID_APP_IDENTIFIERenvironment不匹配 →INVALID_ENVIRONMENTenvironment为 PRODUCTION 而appAppleId为 undefined → 直接抛appAppleId is required when the environment is Production
它同样检查两个 OID(leaf 上的 1.2.840.113635.100.6.11.1、intermediate 上的 1.2.840.113635.100.6.2.1)以及 intermediate.ca。enableOnlineChecks 为 true 时做 OCSP 吊销检查,否则用 payload 里的 signedDate 作为有效期判定时间点——证书是否过期按签名时刻算,不是按当前时间算。
调用形状(按库源码与 issue 整理,未实测):
import { SignedDataVerifier, Environment } from '@apple/app-store-server-library';
const verifier = new SignedDataVerifier(
[appleRootCaG3], // Buffer[],根证书
true, // enableOnlineChecks
Environment.PRODUCTION, // 必须用库导出的常量,不要自己写字符串
'com.example.app', // bundleId
1234567890 // appAppleId,必须是 number
);
const body = JSON.parse(event.body); // 先 parse
const notification = await verifier.verifyAndDecodeNotification(body.signedPayload);
两个踩过的 issue:
- #184:
VerificationException status 2(INVALID_APP_IDENTIFIER),传参看起来一致但失败。根因是Environment传了自己代码里定义的字符串变量,而不是库导出的常量——值看起来一样,比较不成立。改成库常量后恢复。同一 issue 下还有人指出appAppleId必须是数字(number),传字符串同样得到INVALID_APP_IDENTIFIER。 - #224:Supabase Edge Function(Deno)里调用
verifyAndDecodeNotification报Not implemented: crypto.X509Certificate.prototype.publicKey。维护者答复:库官方只支持 Node,其他运行时可能缺 X509 公钥相关的加密能力。另外必须先JSON.parse请求体,把signedPayload字段传进去,而不是把整个请求体传进去——否则解出来是 null,报Cannot read properties of null (reading 'notificationType')。
七、验签之后才轮到业务分发
notificationType 与 subtype 决定动作:
SUBSCRIBED/INITIAL_BUYDID_RENEWDID_FAIL_TO_RENEW(区分是否在isInBillingRetryPeriod,以及gracePeriodExpiresDate)EXPIREDREFUND、REFUND_DECLINED、REFUND_REVERSEDCONSUMPTION_REQUESTOFFER_REDEEMEDTEST
幂等键用 notificationUUID。同一事件可能重投,处理必须幂等——否则续期事件重放会重复延长有效期,这类问题在「返回 200 但状态没对」的场景里经常一起出现。
八、应答与兜底
应答:返回 2xx 表示接收成功。非 2xx Apple 会重试,重试次数与间隔以官方文档为准。不要用 4xx 表达「业务上不需要这条」,那只会让 Apple 反复重投。
兜底:不能只等通知。还应定时调用 App Store Server API 的 Get Transaction Info / Get All Subscription Statuses 核对状态。沙盒与生产是两个独立端点,App Store 审核环境是 Sandbox。data.environment 为 Sandbox 或 Production,用 Sandbox 数据打生产 endpoint、或反过来,都会落到 INVALID_ENVIRONMENT——这条和 bundleId 不匹配是最常见的两个「密码学全过、业务没动」的原因。