POST
RevenueCat webhook

Overview

The single ingestion point for RevenueCat subscription lifecycle events. Each inbound event is persisted to the webhook_events audit log (keyed by (provider, notificationId)), then projected into the user’s subscriptions row and the denormalised subscriptionStatus mirror on the user document. Per QUESTIONS.md §7.2 the locked decisions are:
  • RevenueCat is the source of truth for subscription state. The local subscriptions collection is a projection — it gets fully rewritten by each accepted event, never patched ad-hoc.
  • Pricing (£5.99/mo, £59.99/yr) is configured in the RevenueCat dashboard, NOT hardcoded server-side.
  • Idempotency is via the unique index on (provider, notificationId) — RevenueCat may redeliver the same event multiple times. On replay the server returns 200 { ok: true, deduped: true } without re-processing.
This endpoint has NO Bearer-token user auth. It authenticates the caller (RevenueCat itself) via a shared secret in the Authorization: Bearer ... header, compared in constant time against the REVENUECAT_WEBHOOK_AUTH environment variable.

Authentication

Webhook-level, NOT user-level. Two distinct failure modes: The compare is done via node:crypto.timingSafeEqual on equal-length buffers, so it leaks no timing information about the expected secret. The 503 path exists so that pointing RC at a dev environment with no secret configured returns a clear “not wired” signal rather than a misleading 401.
Set the REVENUECAT_WEBHOOK_AUTH env var to a high-entropy random string (≥32 bytes base64). Use the same string in the RevenueCat dashboard’s webhook configuration. Rotating it means updating both sides simultaneously.

Path parameters

None.

Query parameters

None.

Request body

RevenueCat posts a single JSON object with the inbound event nested under event. Unknown fields are preserved on the audit row but are not validated — the schema uses z.object(...).loose() at both levels.

Example payload — INITIAL_PURCHASE with trial

Example payload — RENEWAL

Example payload — CANCELLATION

CANCELLATION does NOT revoke access immediately — the local status flips to CANCELLED and access continues until expiration_at_ms, at which point RC will deliver a separate EXPIRATION event that flips the status to EXPIRED.

RC event type → local status transition

See the Paywall and launch phase concept page for the full state diagram.

Response — 200 OK

On replay:

Side effects

On a fresh accept (deduped: false):
  1. One row inserted into webhook_events with processed: false, payload: <full body>.
  2. The user’s subscriptions row is upserted on (originalTransactionId) with the new status + dates.
  3. The user’s subscriptionStatus mirror field is set (denormalised fast-path for the requireActiveSubscription middleware that gates Phase 7 endpoints).
  4. The webhook_events row is flipped to processed: true. If the projection threw, the row is flipped to processed: true with the error message attached and the request fails with 500 INTERNAL_ERROR (RC will retry — the dedup index then short-circuits the next attempt once the bug is fixed).
On replay (deduped: true): no mutations. RC may safely retry the same event indefinitely.

Error responses

Example error — 401 WEBHOOK_VERIFICATION_FAILED

Example error — 503 BILLING_NOT_CONFIGURED

See also

  • Paywall and launch phase — local subscription state machine + how subscriptionStatus interacts with the paywall flag.
  • Get billing state — what the projected status looks like to the client.
  • Idempotency — how the (provider, notificationId) unique index works in general.

curl