代码 通知收到了、200 也回了,用户订阅没续期:Apple V2 通知排障笔记

2026-11-22 09:01:19

通知收到了、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。要做完这几件事:

  1. leaf 由 intermediate 签发;
  2. intermediate 由 root 签发;
  3. root 必须是 Apple 的;
  4. 三者都不能过期;
  5. 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_LENGTH
  • bundleId 不匹配,或生产环境 appAppleId 不匹配 → INVALID_APP_IDENTIFIER
  • environment 不匹配 → INVALID_ENVIRONMENT
  • environment 为 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_BUY
  • DID_RENEW
  • DID_FAIL_TO_RENEW(区分是否在 isInBillingRetryPeriod,以及 gracePeriodExpiresDate)
  • EXPIRED
  • REFUND、REFUND_DECLINED、REFUND_REVERSED
  • CONSUMPTION_REQUEST
  • OFFER_REDEEMED
  • TEST

幂等键用 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 不匹配是最常见的两个「密码学全过、业务没动」的原因。

复制全文 生成海报 App Store 内购 JWS验签 订阅 支付回调 PHP Node.js

推荐文章

程序员茄子在线接单