Chapter 10: Webhooks

Receiving subscription event notifications from scratch means setting up a Cloud Pub/Sub topic, creating a push subscription, deploying an endpoint to receive messages, decoding base64 payloads, dispatching by notification type, and implementing idempotency to handle duplicate deliveries. There are 22 different notification types, each mapping to a specific subscription state change.

RevenueCat webhooks replace all of that. You get one webhook endpoint to configure, and one normalized event schema across all stores.

Setting Up Webhooks

In the RevenueCat dashboard, go to Integrations → Webhooks. Add your endpoint URL. RevenueCat sends an HTTP POST with a JSON payload for every relevant event.

There is no Cloud Pub/Sub to configure. No base64 decoding. No service account credentials for your endpoint. RevenueCat sends standard HTTPS POST requests with a X-RevenueCat-Signature header for verification.

The Event Schema

Every RevenueCat webhook has this shape:

{
  "api_version": "1.0",
  "event": {
    "id": "evt_xxxxxxxxxxxxxxxxxxxxxxxx",
    "type": "INITIAL_PURCHASE",
    "app_user_id": "user_12345",
    "aliases": ["$RCAnonymousID:abc123"],
    "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",
    ...
  }
}

The key field is entitlement_ids, RevenueCat has already mapped the product to your entitlement. Your webhook handler does not need to know which product maps to which access level. It just checks which entitlements were affected.

Event Types

A Minimal Webhook Handler

// Server-side (example in Kotlin/Ktor)
post("/revenuecat/webhook") {
    val body = call.receiveText()
    val signature = call.request.headers["X-RevenueCat-Signature"]

    if (!verifySignature(body, signature, webhookSecret)) {
        call.respond(HttpStatusCode.Unauthorized)
        return@post
    }

    val event = Json.decodeFromString<RevenueCatEvent>(body)

    when (event.type) {
        "INITIAL_PURCHASE", "RENEWAL", "UNCANCELLATION" ->
            db.grantEntitlements(event.appUserId, event.entitlementIds)
        "EXPIRATION" ->
            // Subscription has ended, revoke access immediately
            db.revokeEntitlements(event.appUserId, event.entitlementIds)
        "CANCELLATION" ->
            // User has opted out of renewal but still has access until expirationAtMs.
            // Schedule revocation, do NOT revoke immediately.
            db.scheduleEntitlementRevocation(event.appUserId, event.entitlementIds, event.expirationAtMs)
        "BILLING_ISSUE" ->
            db.flagBillingIssue(event.appUserId)
    }

    call.respond(HttpStatusCode.OK)
}

Idempotency

RevenueCat may deliver the same event more than once. Use event.id as an idempotency key. If you have already processed an event with that ID, return 200 without re-processing.

Retries

RevenueCat retries failed webhook deliveries with exponential backoff. Return a 2xx response immediately if you received the event successfully, even if your processing is asynchronous. If your handler takes too long, RevenueCat may time out and retry.