Last updated: March 13, 2026

How to process App Store Server Notifications V2 for Apple subscriptions

If you build a subscription app for iPhone, iPad, or Mac, Apple webhooks can get complicated fast.

Apple does not send plain JSON that you should trust right away. In App Store Server Notifications V2, Apple sends a signedPayload. Your server needs to verify that it really came from Apple before using it. Apple also sends important fields like notificationUUID, signedTransactionInfo, signedRenewalInfo, and appAccountToken.

That is where SubTru helps. SubTru gives subscription apps a cleaner way to process Apple subscription webhooks. We verify the webhook, make sure it belongs to the right app, handle retries safely, and turn Apple's event data into a simple subscription record your app can use.

What are Apple subscription webhooks?

Apple uses App Store Server Notifications to tell your server when something important happens with an in-app purchase or auto-renewable subscription. These notifications can tell you about renewals, refunds, billing problems, expirations, and other key changes.

In plain English, Apple sends updates to your backend so your app can stay in sync with the customer's real subscription state.

What Apple sends in App Store Server Notifications V2

In Version 2, the main field is called signedPayload. Apple says you should verify that signed JWS before trusting the decoded payload. Apple's notification data can also include app metadata plus nested signed data such as signedTransactionInfo and signedRenewalInfo.

How SubTru verifies Apple webhooks

SubTru verifies Apple webhooks before they can change subscription access.

1. We receive the webhook at a project-scoped Apple endpoint.
2. We read the raw request body.
3. We verify the signedPayload JWS.
4. We decode the notification data.
5. We check app identity values like bundleId, environment, and appAppleId when needed.
6. We validate nested signed data such as signedTransactionInfo and signedRenewalInfo.
7. We make sure the event belongs to the correct SubTru project.
8. We deduplicate the event so retries do not create duplicate writes.
9. We map the Apple event into one normalized subscription state.

That matters because a fake webhook, a broken webhook, or a webhook meant for the wrong app should never update customer access.

How signedPayload verification works

Apple's signedPayload is a signed JWS. Apple's docs and server libraries explain that you should verify the signature and verify the certificate chain before trusting the data. Apple also uses an x5c certificate chain for signed data in this system.

In simple terms, SubTru does three things:

• verify the certificate chain
• confirm the JWS signature
• perform revocation checks

That helps answer the question that matters most: did Apple really sign this webhook? If the answer is no, SubTru does not treat the payload as trusted business data.

How SubTru makes sure the webhook belongs to the right app

A valid Apple signature is only part of the job.

SubTru also checks that the webhook belongs to the right app and environment. Apple's notification and transaction data include app identity fields such as bundleId, appAppleId, and environment. This extra check helps prevent cross-app mistakes, especially if a team manages more than one app or both production and sandbox traffic.

How Apple webhook retries work

Apple retries unsuccessful App Store Server Notifications in production. Apple says Version 2 notifications retry five times after the previous unsuccessful attempt: at 1, 12, 24, 48, and 72 hours. Apple also notes that sandbox delivery does not follow the same retry pattern.

That means your system should treat Apple webhooks as at-least-once delivery. In real life, the same event may arrive more than once, and your backend has to handle that safely.

Why idempotency matters for Apple webhooks

Apple includes a unique notificationUUID for each notification. That gives you a clean way to deduplicate retry deliveries.

SubTru uses notificationUUID to make Apple webhook processing idempotent. So if Apple sends the same event again, SubTru can safely ignore the duplicate instead of writing the same subscription update twice.

When SubTru returns 200 and when it returns 500

Response codes matter because they affect whether Apple retries the webhook.

SubTru follows a simple policy:

• If the payload has a permanent problem, we return success and do not ask Apple to retry.
• If the problem is temporary on our side, we return a server error so Apple can try again.

Examples of success cases in SubTru:

• invalid signed payload
• missing required fields
• unsupported notification type
• bad payload data that will not become valid later

Examples of retryable cases in SubTru:

• temporary internal processing failure
• temporary certificate validation issue
• database or infrastructure problem that may succeed on retry

This is SubTru's webhook handling policy. It is designed to avoid pointless retries while still recovering from short outages.

How SubTru normalizes Apple subscription state

Apple sends a lot of useful detail, but most apps do not want to build access logic around dozens of low-level webhook cases.

SubTru maps Apple events into a simpler subscription model your app can use across providers.

• customer identity
• provider subscription ID
• product ID
• current period end
• cancel at period end
• normalized subscription status

Apple includes a status field in Version 2 notification data for auto-renewable subscriptions, and SubTru uses it as an important signal when normalizing subscription state. That helps us handle edge cases more accurately, including refunds, billing retry, grace period, and expiration.

How SubTru links Apple webhooks to your users

For direct subscriptions, the cleanest identity bridge is appAccountToken.

Apple defines appAccountToken as a UUID that you generate to associate a customer's purchase with the resulting App Store transaction. When your app sends appAccountToken, SubTru uses it to link Apple transactions to your customer record.

Common Apple webhook mistakes

• Trusting the webhook too early. If you trust signedPayload before verification, you risk updating access from untrusted data.
• Skipping app identity checks. A valid signature does not automatically mean the event is for the right app.
• Not handling retries. Apple retries failed production deliveries, so duplicate deliveries are normal.
• Guessing subscription state from notification type alone. Apple's newer notification data includes a status field to make subscription state clearer.
• Poor logging. Teams need to know what Apple sent, what was verified, and whether the event was processed, ignored, duplicated, or failed.

Why this matters for subscription apps

Bad Apple webhook handling causes real business problems:

• active users may lose access
• canceled users may keep access too long
• refunds may be handled the wrong way
• duplicate deliveries may create duplicate writes
• support teams may not know what happened

Apple webhooks are powerful, but they are not simple. SubTru gives subscription apps a project-scoped Apple webhook pipeline with verification, idempotency, logging, and normalized subscription state built in.

Frequently asked questions

Does Apple send plain JSON webhooks?

No. In App Store Server Notifications V2, the main payload is signedPayload, and Apple says you should verify it before trusting it.

Does Apple retry failed Apple webhooks?

Yes. Apple says production Version 2 notifications retry five times at 1, 12, 24, 48, and 72 hours after the previous unsuccessful attempt.

Why is idempotency important for Apple webhooks?

Because Apple webhook delivery is at-least-once. The same event can be sent more than once, and notificationUUID gives you a way to deduplicate it.

Should I still check app identity after signature verification?

Yes. Signature verification shows the payload was signed by Apple. You still need to confirm the notification is for the correct app and environment.

What is appAccountToken?

appAccountToken is a UUID you create to connect an App Store purchase to a customer account in your own system.

Build on Apple webhooks without rebuilding the hard parts

SubTru gives subscription apps a better way to handle Apple subscription webhooks.

Instead of stitching together signed payload verification, retries, deduplication, appAccountToken mapping, and subscription state logic on your own, you can use SubTru to keep Apple subscription events clean, accurate, and in sync with your access system.