Terminal
Terminal/Skill
Covers handling RevenueCat webhook events on your backend: signature checks, duplicate handling by event ID, and what to do on cancellation, expiry, and renewal.
By RevenueCat
Works with
npx skills add revenuecat/ai-toolkit --skill rc-webhooksYou configure one endpoint. RevenueCat posts one normalized JSON event schema for every store. Your job on the server side is to verify the signature, deduplicate by event.id, and dispatch per event type.
Confirm what you are wiring up before touching code.
app_user_id.event.type and read event.entitlement_ids. 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",
"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"
}
}
Pick the right action for each event type before you write the handler.
| Event type | Meaning | Handler action |
|---|---|---|
INITIAL_PURCHASE | First paid transaction for this user and product. | Grant entitlements in entitlement_ids. |
RENEWAL | Subscription renewed, including resubscription after an EXPIRATION. | Grant or extend entitlements in entitlement_ids. |
CANCELLATION | User turned off auto renew. Access continues until expiration_at_ms. | Schedule revocation at expiration_at_ms. Do not revoke now. |
UNCANCELLATION | User re enabled auto renew before expiry. | Cancel any scheduled revocation. Keep entitlements active. |
EXPIRATION | Subscription actually ended. | Revoke entitlements now. |
BILLING_ISSUE | Payment failed. User may be in grace period or on hold. | Flag the account. Do not revoke yet. RevenueCat sends EXPIRATION if recovery fails. |
PRODUCT_CHANGE | User switched plan (upgrade, downgrade, or cross grade). | Update the product on record. Entitlement state follows entitlement_ids. |
SUBSCRIBER_ALIAS | Two app user IDs were merged into one identity. | Merge your local records for the aliased IDs. |
TRANSFER | A transaction moved from one app user ID to another. | Move entitlements from the old ID to the new ID. |
Key decisions baked into this table:
CANCELLATION is not an access change. It is an intent signal. Revoking now is a bug that deletes paid access the user still owns.EXPIRATION is the access change. This is when you revoke.EXPIRATION fires RENEWAL, not INITIAL_PURCHASE. Your RENEWAL branch must be safe to run against a user whose entitlements are currently revoked, which means it must grant, not just extend.BILLING_ISSUE is not revocation. Revoking on BILLING_ISSUE cuts off users who are still inside Google Play grace period or account hold.Wire up a handler that verifies, deduplicates, and dispatches.
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<RevenueCatEnvelope>(body).event
handleEvent(event)
call.respond(HttpStatusCode.OK)
}
Return 2xx as soon as the event is persisted. If processing is slow, enqueue it and acknowledge. A slow handler causes retries and duplicate deliveries.
RevenueCat can redeliver the same event. event.id is the idempotency key.
suspend fun handleEvent(event: RcEvent) {
if (processedEvents.insertIfAbsent(event.id)) {
dispatch(event)
}
// Already processed: fall through, responder still returns 200.
}
insertIfAbsent must be atomic in your store (a unique index on event_id plus an insert that swallows duplicate key errors works). Do all downstream writes in the same transaction as the event ID insert so a crash mid handler does not leave you with a marked but unapplied event.
suspend fun dispatch(e: RcEvent) = when (e.type) {
"INITIAL_PURCHASE", "RENEWAL", "UNCANCELLATION" ->
db.grantEntitlements(e.appUserId, e.entitlementIds, e.expirationAtMs)
"CANCELLATION" ->
db.scheduleRevocation(e.appUserId, e.entitlementIds, e.expirationAtMs)
"EXPIRATION" ->
db.revokeEntitlements(e.appUserId, e.entitlementIds)
"BILLING_ISSUE" ->
db.flagBillingIssue(e.appUserId)
"PRODUCT_CHANGE" ->
db.updateProduct(e.appUserId, e.productId, e.entitlementIds)
"SUBSCRIBER_ALIAS", "TRANSFER" ->
db.mergeIdentity(e)
else -> Unit
}
Notes that match the handbook:
grantEntitlements on RENEWAL must be idempotent and additive so a resubscribe after EXPIRATION restores access.scheduleRevocation stores a pending job keyed by (app_user_id, entitlement_id) that fires at expiration_at_ms. If an UNCANCELLATION arrives first, cancel the job. If an EXPIRATION arrives first, let the EXPIRATION handler revoke and drop the pending job.{
"api_version": "1.0",
"event": {
"id": "evt_01HABCXYZ0000000000000010",
"type": "CANCELLATION",
"app_user_id": "user_12345",
"product_id": "premium_monthly",
"purchased_at_ms": 1700000000000,
"expiration_at_ms": 1702592000000,
"entitlement_ids": ["pro_access"],
"store": "PLAY_STORE",
"environment": "PRODUCTION"
}
}
The user keeps pro_access until 1702592000000. Schedule revocation for that timestamp.
{
"api_version": "1.0",
"event": {
"id": "evt_01HABCXYZ0000000000000011",
"type": "EXPIRATION",
"app_user_id": "user_12345",
"product_id": "premium_monthly",
"expiration_at_ms": 1702592000000,
"entitlement_ids": ["pro_access"],
"store": "PLAY_STORE",
"environment": "PRODUCTION"
}
}
Revoke pro_access for user_12345 as soon as you process this.
When a lapsed user resubscribes, RevenueCat sends RENEWAL, not INITIAL_PURCHASE.
{
"api_version": "1.0",
"event": {
"id": "evt_01HABCXYZ0000000000000012",
"type": "RENEWAL",
"app_user_id": "user_12345",
"product_id": "premium_monthly",
"purchased_at_ms": 1705270400000,
"expiration_at_ms": 1707862400000,
"entitlement_ids": ["pro_access"],
"store": "PLAY_STORE",
"environment": "PRODUCTION"
}
}
Your RENEWAL branch must grant entitlements, not assume they already exist. If you only extend an existing expiry, the resubscribed user stays locked out.
X-RevenueCat-Signature.event.id is a no op and still returns 200.CANCELLATION does not revoke access. The user retains entitlements until expiration_at_ms.EXPIRATION revokes access for the IDs in entitlement_ids.RENEWAL arriving after an EXPIRATION restores access for the same app_user_id.BILLING_ISSUE flags the account without revoking.