in-app-purchases

Subscriptions without 2 AM incidents

The architecture rule everything else hangs on

Entitlement truth lives on your server, not in the client. The purchase SDK tells the client "probably premium" fast; the webhook pipeline tells your database "actually premium" reliably. The client renders from server state and treats its local SDK state as an optimistic hint.

Every horror story in this domain is a variation of trusting the client: premium flags in AsyncStorage, entitlement checks that only run at purchase time, or webhook handlers that were never verified against replay.

RevenueCat wiring that holds up

• Identify the user to the SDK with your own auth user id after sign-in. Anonymous ids merging into identified ids is where "user bought on the wrong account" tickets are born.
• Configure once at startup with the platform key; render from customerInfo listeners rather than one-shot fetches, so a purchase completing in the background updates the UI without a restart.
• Decide your transfer policy consciously. "Transfer to new app user id" versus blocking transfers changes what happens when one store account signs into a second app account. Whichever you pick, enforce ownership rules in your own database guards; the SDK setting alone is not a policy.
• Restore purchases must be a visible button (App Store review expects it) and must resolve through the same server-side reconciliation as a fresh purchase.

Webhooks: the part that must be boring

• Verify the sender on every request. RevenueCat gives you two checks: the Authorization header value configured in the dashboard (compare the whole string), and optional HMAC signing, which adds X-RevenueCat-Webhook-Signature: t=<unix seconds>,v1=<hex> where v1 is HMAC-SHA256 over <t>.<raw body> with the signing secret. Turn signing on, verify against the raw request bytes before any JSON parsing, and reject timestamps outside a few minutes; the secret is shown once at creation, so store it immediately. An unverified webhook endpoint is an open "make me premium" API.
• Answer fast. RevenueCat disconnects after 60 seconds and retries a failed or timed-out delivery up to 5 times with growing delays (5, 10, 20, 40, 80 minutes), then gives up. A slow handler therefore produces duplicates first and lost events second: commit the dedupe record and the upsert, return 200, and push anything slow (email, analytics, CRM sync) to a queue.
• If the endpoint runs on a platform that enforces its own auth by default (Supabase Edge Functions and their JWT verification, for example), remember the store's webhook sender cannot present your platform's JWT. Shared-secret endpoints must have platform JWT verification disabled and their own secret check enabled, or every event bounces with 401 and premium "never arrives".
• Deduplicate by event id. Webhook senders retry; your handler will see the same event twice on a bad day.
• Store the environment (SANDBOX vs PRODUCTION) on every event and subscription row, and filter sandbox out of admin dashboards and metrics. Mixed environments make revenue numbers lie.
• Reconcile, don't accumulate: handlers should upsert the subscription to the state the event describes, so replays and out-of-order deliveries converge instead of corrupting.
• A runtime-neutral handler skeleton with the dedupe and transaction contracts spelled out is in reference.md.