Subscription webhooks for iOS and Android purchases in RevenueCat's format

1. 01

   Add a webhook

   In the dashboard open Integrations, then Webhooks, then Add webhook, or call POST /v2/projects/{project_id}/integrations/webhooks. Optionally set an authorization header, an environment and an event filter.

2. 02

   Keep the signing secret

   The whsec_ signing secret is shown once, in the answer. Store it as a secret in your backend.

3. 03

   Verify the signature

   Read the raw body bytes. The header is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the secret. Refuse the request if t is more than 5 minutes from your clock.

4. 04

   Answer 200 and deduplicate

   Only an HTTP 200 counts as delivered. A delivery can arrive twice, so ignore an event.id you have handled. Keep the handler fast, because RevenueDot waits at most 60 seconds.

5. 05

   Send a test event

   Use Send test event in the dashboard. It sends a purchase-shaped TEST event signed like the others.

RevenueDot signs again on every attempt, so t is the attempt's time. Every field of every event type is on the webhook events reference.

POST /webhooks/revenuedot HTTP/1.1
Content-Type: application/json
User-Agent: RevenueDot-Webhooks/1.0
Authorization: Bearer my-shared-token
X-RevenueCat-Webhook-Signature: t=1790800914,v1=0a1552334e825926036f7efe21527800ea45caa63eca523c6120c6da9041ef99

{"api_version":"1.0","event":{"id":"66339910-3BFF-49F4-B873-D1283D673DE2","type":"INITIAL_PURCHASE","app_user_id":"user_1","product_id":"pro_monthly","entitlement_ids":["pro"],"period_type":"NORMAL","environment":"SANDBOX","store":"TEST_STORE","price":9.99,"currency":"USD","presented_offering_id":"default"}}

Runnable receivers for Node.js with Express, Next.js, Python with FastAPI and Go are in the examples repository.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySignature(rawBody, header, secret, { now = new Date(), toleranceSeconds = 300 } = {}) {
  const match = /(?:^|,)\s*t=(\d+)\s*,\s*v1=([0-9a-f]{64})\s*(?:,|$)/.exec(header ?? "");
  if (!match) return false;
  const timestamp = Number(match[1]);
  // Refuse old deliveries so a captured request cannot be replayed.
  if (Math.abs(Math.floor(now.getTime() / 1000) - timestamp) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(timestamp + ".").update(rawBody).digest();
  const received = Buffer.from(match[2], "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Each webhook can filter by environment, app and event type. Two webhooks each receive every event that matches. Order is not guaranteed, so use the timestamps in the event or fetch the customer's current state.

• Lifecycle: INITIAL_PURCHASE, RENEWAL, CANCELLATION, UNCANCELLATION, NON_RENEWING_PURCHASE, SUBSCRIPTION_PAUSED, EXPIRATION, BILLING_ISSUE, PRODUCT_CHANGE, SUBSCRIPTION_EXTENDED, REFUND_REVERSED and TRANSFER.
• Price increases: PRICE_INCREASE_CONSENT_REQUIRED and PRICE_INCREASE_CONSENT_APPROVED.
• More: VIRTUAL_CURRENCY_TRANSACTION, EXPERIMENT_ENROLLMENT, PURCHASE_REDEEMED and TEST. SUBSCRIBER_ALIAS goes only to webhooks whose filter names it.
• Opt-in RevenueDot types for web funnels: FUNNEL_VIEWED, FUNNEL_STEP_COMPLETED and FUNNEL_PURCHASE.
• Never sent: TEMPORARY_ENTITLEMENT_GRANT, because RevenueDot never grants access it has not verified, and INVOICE_ISSUANCE, which only RevenueCat Billing issues.