Skip to main content

Apple App Store Server Notifications

RevenueCat does not require server notifications from the App Store, however doing so can speed up webhook and integration delivery times, reduce lag time for Charts, and allow you to use our Handling Refund Requests feature.

Setup Instructions​

Apple server-to-server notifications should be set up in App Store Connect with the URL provided in the RevenueCat dashboard.

  1. Navigate to your iOS app under Project settings > Apps in the RevenueCat dashboard.
  2. Scroll to the Apple Server to Server notification settings section, and copy the entire URL provided under Apple Server Notification URL. Screen Shot 2021-12-01 at 11.34.04 AM
  3. Log in to App Store Connect and select your app.
  4. Under the App Information > App Store Server Notifications section, paste the entire URL from RevenueCat in both the Production Server URL field and the Sandbox Server URL field. You can use either Version 1 or Version 2 notifications, but Version 2 notifications are recommended to use features such as auto-detecting price changes. Screen Shot 2021-11-03 at 10.03.27 AM

Considerations​

RevenueCat will be able to process V1 or V2 notifications, however, we recommend utilizing V2 for the following reasons:

Here are some key points to keep in mind when considering this switch:

  • RevenueCat continues to operate normally without relying on notifications. Even if there's a brief downtime during the transition, there is no risk of data interruptions.
  • Apple has deprecated their V1 notifications and will continue to make improvements to their V2 notifications.
  • The main reason to stay on V1 notifications is if your system has specific logic tied to V1. For example, if you have custom logic for processing notifications and are forwarding V1 notifications from RevenueCat to your own systems or from your systems to RevenueCat. You will have to update your custom logic before making the switch to V2.
📘Only one server notification URL supported

Apple supports separate URLs for production as well as sandbox purchases, but only allows one of each. You should enter the RevenueCat URL for both of these fields if you don't want to receive these notifications on your own server.

If you want to also receive these notifications on your own server for one or both environments, see our guide on setting up RevenueCat to forward the notifications to your server below.

📘Apple S2S notifications update subscriptions for existing users

If RevenueCat receives a notification for a user that doesn't have any purchases in RevenueCat, a 200 code will be sent and the request will be ignored, so the last received notification timestamp won't be updated. Keep this in mind when forwarding events yourself.

If you still want to receive Apple's notifications to your server, you can configure RevenueCat to forward them to a URL that you specify.

  1. Navigate to your iOS app under Project settings > Apps in the RevenueCat dashboard.
  2. Scroll to the Apple Server to Server notification settings section, and enter your server's URL in Apple Server Notification Forwarding URL.
  3. Click Save Changes in the top right corner. This will forward any Apple's server to server notifications that RevenueCat receives to "my-server.com".
📘

If your server needs to have specific hostnames or IP addresses on its allowlist to receive App Store Server Notifications, you can add the hostname dps.iso.aple.com and IP addresses 17.58.0.0/18 and 17.58.192.0/18. These IP addresses are same for sandbox and production.

[Option 2] Forwarding Apple notifications to RevenueCat​

⚠️Use RevenueCat's forwarding functionality instead

While you can forward Apple S2S notifications to RevenueCat, we strongly recommend setting RevenueCat as the S2S notification URL in App Store Connect and letting RevenueCat forward the events to your server to ensure that the events are sent correctly.

Apple only supports a single server notification URL. If you're already using the notifications on your server and are unable to set up RevenueCat's forwarding URL, you can still forward the payload to the Apple Server Notification URL provided in the app settings of your RevenueCat project.

Here's how we recommend doing this:

1. Configure your server to receive Apple notifications​

First, make sure your server meets the criteria outlined in Apple's Enabling App Store Notifications page or you won't receive notifications.

Then, in your app settings on App Store Connect, enter a subscription status URL that links to your server (see step 4 of the Setup Instructions above).

2. Receive Apple notifications on your server​

Apple sends notifications as JSON data via an HTTP POST request to the URL you provided on App Store Connect.

Wherever you handle this POST request in your code, be sure to respond to Apple with a status code. Responding with a 4xx or 5xx status code will permit Apple to retry the post a few more times.

3. Forward Apple notifications to RevenueCat​

As soon as your server successfully receives a notification, send the payload to RevenueCat. To do this, make an HTTP POST request to the Apple Server Notification URL provided in the app settings of your RevenueCat project.

The payload should be passed along as-is in the data value of your request. Any manipulation you want to do with the data should happen after forwarding to RevenueCat.

Here's a basic example of these steps using Node, Express, and Axios:

app.post('/subscription-update', (req, res) => {
  // - Let Apple know we received the notification
  res.status(200).json();

  // - Forward the request body as-is to RevenueCat
  axios.post(process.env.REVENUECAT_URL, req.body)
  .then(response => {
    // - Successfully forwarded to RevenueCat
    console.log("Successfully forwarded to RevenueCat", response);
  })
  .catch(error => {
    // - Consider a retry to RevenueCat if there's a network error or status code is 5xx
    // - This is optional as RevenueCat should recheck the receipt within a few hours
    console.error("Failed to send notification to RevenueCat", error);
  });

  // - Anything else you want to do with the request can go here
});

Tracking new purchases using Apple App Store Server Notifications​

By default, RevenueCat ignores any Apple App Store Server Notifications for purchases that have not yet been posted to the RevenueCat API by one of our SDKs or from your own backend. For RevenueCat to track new purchases from Apple App Store Server Notifications, you can enable the "Track new purchases from server-to-server notifications" option in our Dashboard. This allows RevenueCat to process new purchases from server-to-server notifications that are not yet in our system. This ensures all purchases are tracked, even in the case of network issues between your app and RevenueCat’s backend or if your customer was using a version of the app without the RevenueCat SDK.

Considerations​

  • The subscriber's app user ID will be taken from the appAccountToken field of the transaction.
    • If the appAccountToken is set and does not match with an existing subscriber: RevenueCat will create a new subscriber with an app user ID matching the appAccountToken value set.
    • If the appAccountToken is set and matches with an existing subscriber: No new subscriber will be created, and the purchase will be linked to that existing subscriber.
    • If the appAccountToken is not set: RevenueCat will generate an anonymous app user ID to associate that purchase with.
  • If you are using RevenueCat's SDK to track purchases, we may receive the notification directly from the store before the SDK. When this happens, we will follow the app user ID logic as described in the bullet point above, and then proceed with your transfer behavior for the new app user ID sent by the SDK.
⚠️Customer attributes in events

RevenueCat will start processing the purchase as soon as we receive the Apple server notification. If you rely on RevenueCat customer attributes being attached to the customer before the purchase is created on RevenueCat (e.g: sending customer attributes to your enabled third-party integrations or webhooks), you should make sure to send and sync the customer attributes as soon as you have them or before the purchase is completed.

⚠️

If you have enabled Keep with original App User ID or Transfer if there are no active subscriptions transfer behavior, we highly recommend turning this setting off unless you are not setting the appAccountToken or if the appAccountToken will match their RevenueCat app user ID.