Stripe Server Notifications

RevenueCat does not require server notifications from Stripe, however doing so can speed up webhook and integration delivery times and reduce lag time for Charts.

⚠️Send Stripe token to RevenueCat

Stripe Server Notifications only work if the receipt exists in RevenueCat when the event is dispatched from Stripe. If the receipt doesn't exist, the event will fail. This includes test events from Stripe.

You'll need to follow our Stripe Web Payments guide and send your purchase tokens to RevenueCat before proceeding with this guide.

Setup Instructions

1. Navigate to your app settings in the RevenueCat dashboard by selecting your app from Project Settings > Apps.
2. Expand the Webhook Configuration section and copy the endpoint provided under Stripe Webhook Endpoint.

3. Log in to Stripe and go to the Webhooks dashboard.
4. Click Add endpoint, paste the URL in the Endpoint URL field and select the following events:

• customer.subscription.updated
• customer.subscription.deleted
• charge.refunded
• invoice.updated

If you plan to enable the "Track new purchases from server-to-server notifications" feature, you should also select the following events:

• customer.subscription.created
• checkout.session.completed

It's important to only select these events.

⚠️

If you choose other events besides what's listed above, our API will respond with an error, and Stripe will eventually disable the webhook.

5. Click Add endpoint. You might be asked to enter your password.
6. Copy the Signing Secret value and go back to your app settings in the RevenueCat Dashboard (select your app under Project Settings > Apps).

7. Paste it in the Stripe Webhook Secret input field and save. The input field should now look like this:

Tracking new purchases using Stripe Server Notifications

By default, RevenueCat will not process Stripe Server Notifications for any purchases that have not yet been posted to the RevenueCat API from your own backend. For RevenueCat to track new purchases from Stripe 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 server's and RevenueCat's.

App User ID Detection Methods

RevenueCat provides flexible ways to detect the App User ID for purchases coming through Stripe Server Notifications. The Stripe purchase will be associated with the detected App User ID.

1. Use anonymous App User IDs: RevenueCat will generate a RevenueCat anonymous App User ID to associate the purchase with.
2. Use Stripe Customer ID as App User ID: RevenueCat will use the Stripe Customer ID field as the RevenueCat App User ID. Only select this option if you plan on using Stripe's Customer ID as your customer's App User ID throughout your system.
3. Read App User ID from a Stripe metadata field: If you are storing your customer's RevenueCat App User ID through Stripe metadata, you can specify the metadata field name in the Metadata field key textbox. RevenueCat will look for this field in the Checkout Session metadata for checkout sessions and in the Subscription metadata for subscriptions. Ensure that the metadata value will exactly match your RevenueCat App User ID.

📘Additional information about using Stripe Customer ID as App User ID

In some cases, a Stripe Checkout Session may have a NULL value for the Stripe Customer ID. This can happen when a purchase is made by a "guest customer". In these instances, RevenueCat will associate the purchase with an anonymous App User ID.

Considerations

• If your setup involves you manually sending us the Stripe token, RevenueCat may receive the notification from Stripe before your server's request. In this case:
  • The App User ID detection method described above will be applied.
  • RevenueCat will then follow your transfer behavior for the App User ID provided in your request.

⚠️Customer attributes in events

RevenueCat will start processing the purchase as soon as we receive Stripe's 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.

Stripe Webhook 400 Errors

Sometimes you may experience 400 errors when connecting to Stripe. Generally these happen when there is something wrong with your configuration or your Stripe account is not properly connected to RevenueCat.

Configuration

Two common configuration errors are with events and the webhook secret.
One webhook endpoint should contain all of the events, not one endpoint per event, and the only events supported are those listed above in step 4. The Stripe Webhook Secret should be properly set in your RevenueCat project settings in the Stripe Webhook Secret field. If this field is missing or not identical to the secret generated in Stripe, 400 errors will occur.

Reconnecting Stripe

When debugging connection issues with Stripe, it may be necessary to reconnect Stripe and RevenueCat. Make sure to use the email that owns RevenueCat project. To reconnect, follow these steps:

1. Disconnect from Stripe in the RevenueCat dashboard
2. Uninstall the app from your Stripe account in the Stripe Dashboard
3. In the RevenueCat dashboard, click 'Connect to Stripe'
4. Install the RevenueCat app in the Stripe dashboard
5. Ensure the 'test mode' switch is off in Stripe
6. Click 'Sign in with RevenueCat' in Stripe in the RevenueCat app's settings

⚠️

When reconnecting to Stripe, the webhook secret can change so make sure it is the same in both Stripe and RevenueCat.