webhooks

RevenueCat Webhooks

You configure one endpoint. RevenueCat posts one normalized JSON event schema for every store. Your job on the server side is to authenticate the request, deduplicate by event.id, and update your records from the customer the event touches.

Phase 1: Discover

Confirm what you are wiring up before touching code.

• You own a server side HTTPS endpoint that accepts POST with a JSON body.
• You set an authorization header value on the webhook integration in the RevenueCat dashboard under Integrations then Webhooks. If you also turn on HMAC webhook signing there, you stored its signing secret, which the dashboard shows only once.
• Google Play Real Time Developer Notifications are connected to RevenueCat. Without them RevenueCat may learn about a refund of a one time purchase only when the app next opens.
• You have durable storage to record processed event IDs and entitlement state per user.
• You have the secret REST API key on the server, to re-read customers with GET /v1/subscribers/{app_user_id}.
• You understand that RevenueCat has already mapped products to entitlements, so the customer it returns lists every entitlement with its expires_date, expired ones included. You do not maintain a product to entitlement table on your backend.

Every event has this outer shape:

{
  "api_version": "1.0",
  "event": {
    "id": "evt_01HABCXYZ0000000000000001",
    "type": "INITIAL_PURCHASE",
    "app_user_id": "user_12345",
    "original_app_user_id": "$RCAnonymousID:8b1d0e5c4f2a4d3e9c6b7a5f4e3d2c1b",
    "aliases": ["$RCAnonymousID:8b1d0e5c4f2a4d3e9c6b7a5f4e3d2c1b", "user_12345"],
    "product_id": "premium_monthly",
    "period_type": "NORMAL",
    "purchased_at_ms": 1700000000000,
    "expiration_at_ms": 1702592000000,
    "store": "PLAY_STORE",
    "environment": "PRODUCTION",
    "entitlement_ids": ["pro_access"],
    "transaction_id": "GPA.1234-5678-9012-34567"
  }
}

Phase 2: Plan

Take access from the customer, not from the event. For every event that can change access, re-read the customer it touches with GET /v1/subscribers/{app_user_id} and store the entitlements RevenueCat reports now. RevenueCat recommends this after any webhook, and it stays correct when events arrive late or out of order: automatic retries follow after 5, 10, 20, 40, and 80 minutes and a dashboard retry can come any time, so a retried EXPIRATION can land after the event that restored access, and another source (a granted entitlement, another store) can still grant an entitlement that one product's EXPIRATION lists. Use the payload only for what the customer does not carry, such as consumable credits.