App Store Server Notifications V2: setup and notification types

App Store Server Notifications V2 are HTTPS POST requests that Apple sends to your server when something changes in a customer's purchase: a new subscription, a renewal, a failed payment, a refund. Each body holds one field, signedPayload, a JSON Web Signature that you verify and decode. You set one production URL and one optional sandbox URL in App Store Connect, answer HTTP 200 to every verified notification, and read the notificationType and subtype to decide what the customer may use.

Sources are Apple's App Store Server Notifications documentation, read on October 1, 2026.

What you need#

• A public HTTPS endpoint. Apple's setup guide says your server must support TLS 1.2 or later.
• Access to App Store Connect with the Account Holder, Admin, App Manager or Marketing role (per Apple's help page).
• An In-App Purchase key if you also call the App Store Server API. See Server-side receipt validation.
• Either your own code to verify and apply notifications, or a backend that does it, such as RevenueDot.

Step 1: Choose the URL#

Pick an HTTPS URL for production, and optionally a second for the sandbox. You can use the same URL for both. If you add a port, Apple requires 443 or a value of 1024 or higher.

With RevenueDot, the URL is generated for you per app: https://api.revenuedot.app/v1/notifications/apple/{app_id} on Cloud, or the same path on your own server.

If your firewall uses an allow list, add Apple's subnet 17.0.0.0/8. Apple says it applies to both sandbox and production.

Step 2: Set it in App Store Connect#

Per Apple's help page:

1. Open your app, then App Information, then App Store Server Notifications under General Information.
2. Under Production Server URL, click Set Up URL, enter the URL, choose Version 2 and click Save.
3. Do the same under Sandbox Server URL.

Apple's notes: if you give only a production URL, the App Store sends both environments there. If you give only a sandbox URL, nothing arrives in production. Version 1 is marked deprecated, and Apple says to use V2 for new implementations. Sandbox metadata changes can take up to an hour to appear.

Step 3: Send a test notification#

Apple's App Store Server API can send a test to your URL. Call Request a Test Notification, then use the returned testNotificationToken with Get Test Notification Status to see how your server answered. The TEST notification arrives in V2 format whichever version you configured.

Apple's open-source Node library shows the call:

const client = new AppStoreServerAPIClient(encodedKey, keyId, issuerId, bundleId, Environment.SANDBOX)
await client.requestTestNotification()

With RevenueDot, the app page shows Ready after the first valid notification, test or real. See store notifications not arriving if it does not.

Step 4: Verify and decode the payload#

Apple's responseBodyV2 page describes the format. The body is JSON with one key:

{ "signedPayload": "eyJhbGciOiJFUzI1NiIsIng1YyI6WyJ..." }

To read it, you split the JWS, Base64URL-decode the payload and validate the signature with the algorithm named in the header. The decoded payload holds notificationType, subtype and a data object. When present, data.signedTransactionInfo and data.signedRenewalInfo are themselves signed JWS strings that you verify the same way. Never act on a notification you did not verify.

Apple's library does this for you. In Node:

const verifier = new SignedDataVerifier(appleRootCAs, true, Environment.PRODUCTION, bundleId, appAppleId)
const notification = await verifier.verifyAndDecodeNotification(signedPayload)

Apple's library page lists the same functions in Swift, Java, Python and Node, plus verifyAndDecodeTransaction and verifyAndDecodeRenewalInfo. The first argument is Apple's root certificates from its PKI site.

Also check that the bundleId in the payload is yours, and that the environment matches the URL that received it.

Step 5: Answer correctly#

Apple's response rules:

• HTTP 200 to 206 means success.
• HTTP 40x or 50x makes the App Store retry.
• All other codes count as unsuccessful.

After a failure, V2 retries five times, at 1, 12, 24, 48 and 72 hours after the previous attempt. Retries are production-only: the sandbox tries once. If your server was down, call Get Notification History, which returns notifications for the past 180 days (30 in the sandbox). You can always rebuild state with Get Transaction History and Get All Subscription Statuses.

Do the real work after you answer. Verify, store the raw body, return 200, then process from a queue. A slow handler that times out looks like a failure and causes retries and duplicates. Deduplicate on notificationUUID.

Every notification type#

Apple's notificationType page defines these values. The last column says what RevenueDot does with each.

Apple groups the same events by what happened in its life-cycle tables. The patterns you will meet most:

Apple says that after a billing failure the App Store keeps retrying for 60 days, or until the customer fixes the problem or cancels.

How RevenueDot handles each notification#

RevenueDot's endpoint, POST /v1/notifications/apple/{app_id}, does this for every request:

1. It stores the raw body first, so nothing is lost.
2. It verifies the JWS chain against Apple's root certificate.
3. It checks the bundle ID, and your Apple app ID if you set one. A wrong bundle gets 400, which shows as failed in App Store Connect.
4. For a state-changing type, it updates the subscription, then compares the old and new state and records events such as RENEWAL, CANCELLATION or BILLING_ISSUE. Your webhooks get them, in RevenueCat's format.
5. It answers 200, including for notifications about purchases it has never seen. Those are stored, and applied only when Track new purchases from server-to-server notifications is on.
6. It answers 500 only when it fails itself, so Apple retries.

EXPIRATION comes from a background job, not from Apple's EXPIRED, so access ends at the right time even when a notification is late. See subscriptions and events for which change gives which event.

Forwarding during a migration#

App Store Connect holds one production URL per app, so only one system can receive Apple's notifications directly. If you move from RevenueCat to RevenueDot, point Apple at RevenueDot and let it forward each notification to RevenueCat. Apple's enabling guide describes the single-URL setup.

curl -s -X POST https://api.revenuedot.app/v2/projects/$PROJECT_ID/apps/$APP_ID \
  -H "Authorization: Bearer $SECRET_KEY" -H "Content-Type: application/json" \
  -d '{"app_store":{"notification_forward_url":"https://<your RevenueCat App Store notification URL>"}}'

RevenueDot copies the exact body, byte for byte, with a 10-second timeout, in the background, so a slow receiver never delays Apple. The last forward's HTTP status shows on the app page. The dual-run guide has the rest, and the migration post gives the full order. Forwarding was tested with a test URL. It has not yet run against RevenueCat's real notification endpoints.

Common errors and fixes#

Do it with RevenueDot#

1. Create a free account and add an App Store app with your bundle ID.
2. Upload the In-App Purchase key (.p8, Key ID, Issuer ID).
3. Copy the notification URL and set it for production and sandbox in App Store Connect, as Version 2.
4. Request a test notification and wait for Ready.
5. Add a webhook under Integrations, Webhooks to hear about each change in your backend.

Start free on RevenueDot Cloud

FAQ#

What is the difference between App Store Server Notifications V1 and V2?#

V1 sends a plain JSON body with a receipt and is deprecated. V2 sends a signed JWS, signedPayload, with a notification type, a subtype and signed transaction and renewal info. Apple says to use V2 for new implementations.

How many times does Apple retry a failed notification?#

For V2, five times, at 1, 12, 24, 48 and 72 hours after the previous attempt, in production only. The sandbox makes one attempt. Apple's Get Notification History endpoint covers the last 180 days.

What should my endpoint return?#

HTTP 200, or any code from 200 to 206, when you verified and accepted the notification. A 40x or 50x makes Apple retry.

Do I still need the App Store Server API if I use notifications?#

Yes, for recovery and history. Notifications tell you about changes, and the API lets you read the current truth, fetch missed notifications and test your endpoint.

Can two systems receive the same notification?#

Not directly, because App Store Connect holds one production URL per app. Receive in one system and forward the exact body to the other. RevenueDot does this with notification_forward_url.

About RevenueDot. RevenueDot is an open-source (AGPL-3.0) backend for in-app purchases and subscriptions that works with the RevenueCat SDK. Start free on RevenueDot Cloud, free up to $10,000 in monthly tracked revenue, or self-host it with Docker and Postgres. Point the SDK's proxy URL at RevenueDot and keep your app code, your offerings and your customers. Read the quickstart or the code on GitHub.