Webhooks are only available on paid plans.
RevenueCat can send you notifications any time an event happens in your app. This is useful for subscription and purchase events, which will allow you to monitor state changes for your subscribers and react accordingly. For example, you might want to remind your subscribers of the benefits of your app when they decide to unsubscribe, or let them know when there are billing issues.
To start receiving webhook events, register your server URL for your app using RevenueCat's dashboard.
One webhook per app
Each of your apps has a webhook URL field you can set. This way you can decide which of your apps need server side notifications, and where they should be sent.
RevenueCat will send POST requests to your server, in which the body will be a JSON representation of the notification. Your server should return a 200 status code. Any other status code will be considered a failure by our backend. RevenueCat will retry later (up to 5 times) with an increasing delay (5, 10, 20, 40, and 80 minutes). After 5 retries, we will stop sending notifications.
If you're receiving a webhook it's important to respond quickly so you don't accidentally run over a timeout limit. We recommend that apps defer processing until after the response has been sent.
Best Practices: Webhook authorization
We recommended setting an authorization header value via the RevenueCat dashboard. When set, RevenueCat will send this header in every request. Your server can use this to authenticate the webhooks from RevenueCat.
TEST
Test event issued through the RevenueCat dashboard.
✅
✅
❌
❌
INITIAL_PURCHASE
A new subscription has been purchased.
✅
✅
✅
❌
NON_RENEWING_PURCHASE
A customer has made a purchase that will not auto-renew.
✅
✅
❌
✅
RENEWAL
An existing purchase has been renewed.
✅
✅
✅
❌
PRODUCT_CHANGE
A subscriber has changed the product of their subscription.
✅
✅
✅
❌
CANCELLATION
A subscription has been cancelled.
✅
✅
✅
✅
BILLING_ISSUE
There has been a problem trying to charge the subscriber. This does not mean the subscription has expired.
✅
✅
❌
❌
SUBSCRIBER_ALIAS
A new app_user_id has been registered for an existing subscriber.
✅
✅
❌
❌
Webhook events are serialized in JSON. The body of a POST request to your server will contain the serialized event, as well as the API version.
{
"event": {
"type": "INITIAL_PURCHASE",
"id": "CD489E0E-5D52-4E03-966B-A7F17788E432",
"app_user_id": "00005A1C-6091-4F81-BE77-F0A83A271AB6",
"original_app_user_id" : "4BEDB450-8EF2-11E9-B475-0800200C9A66",
"aliases": ["00005A1C-6091-4F81-BE77-F0A83A271AB6", "4BEDB450-8EF2-11E9-B475-0800200C9A66"],
"product_id": "onemonth_free_trial",
"period_type": "TRIAL",
"purchased_at_ms": 1530648507000,
"expiration_at_ms": 1533326907000,
"event_timestamp_ms": 1530648573000,
"store": "PLAY_STORE",
"environment": "SANDBOX"
},
"api_version": "1.0"
}type
String
TEST
INITIAL_PURCHASE
NON_RENEWING_PURCHASE
RENEWAL
PRODUCT_CHANGE
CANCELLATION
BILLING_ISSUE
SUBSCRIBER_ALIAS
id
String
Unique identifier of the event.
event_timestamp_ms
Integer
app_user_id
String
Last seen app user id of the subscriber.
original_app_user_id
String
The first app user id used by the subscriber.
aliases
[String]
All app user ids ever used by the subscriber.
If we have to retry a webhook for any reason, the retry will have the same id and event_timestamp_ms of the first attempt.
product_id
String
Product identifier of the subscription.
entitlement_id
String
Entitlement identifier of the subscription.
It can be NULL if the product_id is not mapped to an entitlement.
period_type
String
Period type of the transaction.
TRIAL, for free trials.
INTRO, for introductory pricing.
NORMAL, standard subscription.
PROMOTIONAL, for subscriptions granted through RevenueCat.
purchased_at_ms
Integer
Time when the transaction was purchased. Measured in milliseconds since Unix epoch
expiration_at_ms
Integer
Expiration of the transaction. Measured in milliseconds since Unix epoch. Use this field to determine if a subscription is still active.
It can be NULL for non-subscription purchases.
store
String
Store the subscription belongs to.
PLAY_STORE
APP_STORE
STRIPE
MAC_APP_STORE
PROMOTIONAL
environment
String
Store environment.
SANDBOX
PRODUCTION
is_trial_conversion
Boolean
Only available for RENEWAL events.
Whether the previous transaction was a free trial or not.
true or false
cancel_reason
String
Only available for CANCELLATION events.
See Cancellation Reasons.
UNSUBSCRIBE
BILLING_ERROR
DEVELOPER_INITIATED
PRICE_INCREASE
CUSTOMER_SUPPORT
UNKNOWN
new_product_id
String
Product identifier of the new product the subscriber has switched to. Only available for App Store subscriptions and PRODUCT_CHANGE events.
UNSUBSCRIBE
Subscriber cancelled voluntarily. This event fires when a user unsubscribes, not when the subscription expires.
✅
✅
✅
❌
BILLING_ERROR
Apple or Google could not charge the subscriber using their payment method.
✅
✅
❌
❌
DEVELOPER_INITIATED
Developer cancelled the subscription.
❌
✅
❌
✅
PRICE_INCREASE
Subscriber did not agree to a price increase.
✅
❌
❌
❌
CUSTOMER_SUPPORT
Customer cancelled through Apple support and received a refund.
✅
❌
❌
❌
UNKNOWN
Apple did not provide the reason of the cancellation.
✅
❌
❌
❌
You can test your server side implementation by purchasing sandbox subscriptions or by issuing test webhook events through RevenueCat's dashboard.
Sandbox notifications
Keep in mind that not all the events are guaranteed to be sent for sandbox subscriptions. This is due to limitations in the sandbox testing environments.
Tracking Subscription Status
Webhooks are commonly used to keep a subscribers status in sync with RevenueCat across multiple systems. The best way to keep a subscription status up-to-date is by updating your system with the entitlement_id and expiration_at_ms from every webhook event. By simplifying your logic to rely on just these attributes the event type no longer matters.
Authorization
You can configure the authorization header used for webhook requests via the dashboard. Your server should verify the validity of the authorization header for every notification.
Response Duration
If your server doesn't finish the response in 60s, RevenueCat will disconnect. We then retry up to 5 times. We recommend that apps respond quickly and defer processing until after the response has been sent.
Delivery Delays
Most webhooks are delivered within 0-2 minutes of the event occurring - cancellation events usually are delivered within 2hrs of the user cancelling their subscription. You should be aware of these delivery times when designing your app.
Future Proofing
You should be able to handle webhooks that include additional fields to what's shown here, including new event types. We may add new fields or event types in the future without changing the API version. We won't remove fields or events without proper API versioning and deprecation.