App Store Server Notifications V2: the complete setup guide

POST /your/notifications/endpoint HTTP/1.1
Content-Type: application/json

{
  "signedPayload": "eyJhbGciOiJFUzI1NiIsIng1YyI6WyJNSUlFTUQuLi4iLCJNSUlFVlEuLi4iLCJNSUlDUXouLi4iXX0.eyJub3RpZmljYXRpb25UeXBlIjoiRElEX1JFTkVXIiwibm90aWZ...cw.MEUCIQDw..."
}

{
  "notificationType": "DID_RENEW",
  "notificationUUID": "002e14d5-51f5-4503-b5a8-c3a1af68eb20",
  "version": "2.0",
  "signedDate": 1783142400000,
  "data": {
    "appAppleId": 1234567890,
    "bundleId": "com.example.yourapp",
    "environment": "Production",
    "signedTransactionInfo": "<another JWS>",
    "signedRenewalInfo": "<another JWS>"
  }
}

// verify.ts: Node 18+, npm i @apple/app-store-server-library
import { readFileSync } from "node:fs";
import {
  Environment,
  SignedDataVerifier,
} from "@apple/app-store-server-library";

// Apple's root CA, downloaded once from
// https://www.apple.com/certificateauthority/ and bundled with your app.
// Every notification's x5c chain must terminate at this certificate.
const appleRoots = [readFileSync("certs/AppleRootCA-G3.cer")];

export function makeVerifier(environment: "Sandbox" | "Production") {
  return new SignedDataVerifier(
    appleRoots,
    true, // enableOnlineChecks: OCSP revocation checks against Apple
    environment === "Production" ? Environment.PRODUCTION : Environment.SANDBOX,
    "com.example.yourapp", // your bundle id (must match data.bundleId)
    // appAppleId is REQUIRED for Production and must be OMITTED for Sandbox.
    // This asymmetry is the single most common verification gotcha.
    environment === "Production" ? 1234567890 : undefined,
  );
}

// app/api/apple/notifications/route.ts (Next.js shown; the shape is
// identical in Express/Fastify: read the JSON body, verify, ack fast,
// do heavy work asynchronously)
import { makeVerifier } from "./verify";

export async function POST(req: Request) {
  const body = (await req.json().catch(() => null)) as
    | { signedPayload?: string }
    | null;
  if (typeof body?.signedPayload !== "string") {
    return new Response("Bad Request", { status: 400 });
  }

  // Peek data.environment WITHOUT verifying, only to pick which verifier
  // to construct. The verifier re-checks the environment against the
  // signature, so lying here buys an attacker nothing: it fails closed.
  const environment = peekEnvironment(body.signedPayload);

  let payload;
  try {
    payload = await makeVerifier(environment).verifyAndDecodeNotification(
      body.signedPayload,
    );
  } catch {
    // Bad signature, broken chain, or bundle/environment mismatch.
    return new Response("Unauthorized", { status: 401 });
  }

  // Apple can deliver the same notification more than once (retries).
  // Dedupe on notificationUUID before acting on it.
  // await recordOnce(payload.notificationUUID, payload);

  // Respond 200 within seconds; anything else counts as a failed delivery.
  return new Response("OK", { status: 200 });
}

function peekEnvironment(signedPayload: string): "Sandbox" | "Production" {
  const claims = JSON.parse(
    Buffer.from(signedPayload.split(".")[1], "base64url").toString("utf8"),
  ) as { data?: { environment?: string } };
  return claims.data?.environment === "Sandbox" ? "Sandbox" : "Production";
}

// manual-verify.ts: what the library does, spelled out. Prefer the
// library in production (it also performs OCSP revocation checks, which
// this sketch omits). npm i jose
import { readFileSync } from "node:fs";
import { X509Certificate } from "node:crypto";
import { compactVerify, importX509 } from "jose";

const APPLE_ROOT_DER = readFileSync("certs/AppleRootCA-G3.cer");

export async function verifySignedPayload(signedPayload: string) {
  // 1. The JWS protected header carries the signing chain in x5c:
  //    [leaf, intermediate, root], each base64 DER.
  const header = JSON.parse(
    Buffer.from(signedPayload.split(".")[0], "base64url").toString("utf8"),
  ) as { alg?: string; x5c?: string[] };
  if (header.alg !== "ES256" || header.x5c?.length !== 3) {
    throw new Error("unexpected JWS header");
  }
  const [leaf, intermediate, root] = header.x5c.map(
    (b64) => new X509Certificate(Buffer.from(b64, "base64")),
  );

  // 2. Pin the root: byte-identical to the Apple Root CA - G3 you
  //    downloaded from apple.com/certificateauthority. Never trust a
  //    chain just because it is internally consistent.
  if (!root.raw.equals(APPLE_ROOT_DER)) throw new Error("untrusted root");

  // 3. Walk the chain: leaf signed by intermediate, intermediate by root,
  //    and every certificate inside its validity window.
  if (
    !leaf.verify(intermediate.publicKey) ||
    !intermediate.verify(root.publicKey)
  ) {
    throw new Error("broken certificate chain");
  }
  const now = Date.now();
  for (const cert of [leaf, intermediate, root]) {
    if (now < Date.parse(cert.validFrom) || now > Date.parse(cert.validTo)) {
      throw new Error("certificate outside its validity window");
    }
  }

  // 4. Verify the ES256 signature with the leaf's public key. Pin the
  //    algorithm list; never let the header choose it for you.
  const key = await importX509(leaf.toString(), "ES256");
  const { payload } = await compactVerify(signedPayload, key, {
    algorithms: ["ES256"],
  });
  const decoded = JSON.parse(new TextDecoder().decode(payload));

  // 5. Finally, check the payload is for YOUR app and THIS endpoint's
  //    environment.
  if (decoded.data?.bundleId !== "com.example.yourapp") {
    throw new Error("wrong bundleId");
  }
  return decoded;
}

// npm i @apple/app-store-server-library. Credentials are an
// App Store Connect API key (see our API key guide).
import {
  AppStoreServerAPIClient,
  Environment,
} from "@apple/app-store-server-library";

const client = new AppStoreServerAPIClient(
  privateKeyP8Contents, // the .p8 file's contents
  "ABC123DEFG",         // Key ID
  "12345678-abcd-1234-abcd-1234567890ab", // Issuer ID
  "com.example.yourapp",
  Environment.SANDBOX,  // or PRODUCTION (tests the matching URL)
);

const { testNotificationToken } = await client.requestTestNotification();

// Give Apple a moment, then ask how delivery went:
const status = await client.getTestNotificationStatus(testNotificationToken!);
console.log(status.sendAttempts);
// → [{ attemptDate: 1783142400000, sendAttemptResult: "SUCCESS" }]
// Other results ("TIMED_OUT", "TLS_ISSUE", "CIRCULAR_REDIRECT", …) tell
// you exactly why Apple could not reach your endpoint.