Revenue
Connect Superwall
On this page
Superwall sends purchase, renewal, refund and subscription events from the App Store, Google Play and its web checkout to a webhook signed with a secret Superwall generates. Webhooks are included on every Superwall plan.
Set up the webhook
Set up revenue tracking in Superwall
Superwall only has purchases to send once it tracks revenue: App Store Connect, Google Play or Stripe (for web checkout) under your app's Integrations → Revenue tracking. For web checkout, open Integrations → Stripe and paste the publishable and restricted keys from the Superwall Stripe app under Live configuration (or Sandbox configuration for test mode). A webhook can be created before this, but nothing is sent until purchases are tracked.
Open Settings → Integrations → Superwall in MetricRaven
Turn on Test mode first if this site should record sandbox purchases only. Copy the webhook URL.
Create a webhook in Superwall
In your Superwall app, open Integrations and choose Webhooks under Webhooks and tools, then Create webhook. Enter a Webhook name, paste the MetricRaven URL as the Webhook URL and keep every event selected under Events to listen for. No custom headers are needed.
Paste the signing secret
Superwall shows the webhook's signing secret (
whsec_…) once, right after you create it. Paste it into the MetricRaven panel and choose Connect. If you lose it, open the webhook in Superwall and choose Rotate secret, then paste the new one: the old one stops working at once.Make a purchase
Superwall sends no test events to these webhooks. After the next purchase (a sandbox purchase on a Test mode connection), MetricRaven shows Connected, Last event and the number of events received.
Link purchases to visitors
Use the same canonical user ID in Superwall's identify and MetricRaven's Identify API: every event carries the app user ID, so the payment joins that person's visits. To link the exact website visit, also set the metricraven_visitor_id user attribute; Superwall sends user attributes with every event. Anonymous Superwall IDs ($SuperwallAlias:…) are never used as the user.
// After sign-in: the same user ID you pass to MetricRaven's identify.
Superwall.shared.identify(userId: user.id)
// Optional: the website visitor ID, if your web-to-app flow carried it safely.
if let visitorId {
Superwall.shared.setUserAttributes(["metricraven_visitor_id": visitorId])
}// After sign-in: the same user ID you pass to MetricRaven's identify.
Superwall.instance.identify(userId = user.id)
// Optional: the website visitor ID, if your web-to-app flow carried it safely.
visitorId?.let {
Superwall.instance.setUserAttributes(mapOf("metricraven_visitor_id" to it))
}// expo-superwall, inside a component under <SuperwallProvider>.
import { useUser } from "expo-superwall";
import { analytics } from "./analytics"; // @metricraven/react-native
const { identify, update } = useUser();
// After sign-in: the same user ID you pass to analytics.identify.
await identify(user.id);
// Optional: link this device's MetricRaven visitor too.
const visitorId = analytics.getVisitorId();
if (visitorId) await update({ metricraven_visitor_id: visitorId });// package:metricraven: the same user ID in MetricRaven and Superwall.
MetricRaven.identify(user.id, {'email': user.email});
await Superwall.shared.identify(user.id);
// Optional: link this install's MetricRaven visitor too.
final visitorId = MetricRaven.visitorId;
if (visitorId != null) {
await Superwall.shared.setUserAttributes({'metricraven_visitor_id': visitorId});
}From your server, set the attribute with Superwall's API instead:
# Server: set the attribute on a Superwall user (API key with the users:write scope).
curl -X POST "https://api.superwall.com/v3/users/$APP_USER_ID/attributes?application_id=$SUPERWALL_APPLICATION_ID" \
-H "Authorization: Bearer $SUPERWALL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"attributes": {"metricraven_visitor_id": "0123456789abcdef0123456789abcdef"}}'Web checkout
A Superwall web checkout link takes the buyer's app user ID in ?app_user_id=. Open it with the MetricRaven visitor ID, or with your own user ID if the buyer is signed in and identified in MetricRaven. An app user ID shaped like a visitor ID (32 hex characters) links the purchase to that visit.
// Browser: open a Superwall web checkout link as this visitor.
// Superwall uses ?app_user_id= as the buyer's app user ID.
const url = new URL("https://YOUR-APP.superwall.app/YOUR_PLACEMENT");
const visitorId = window.analytics?.getVisitorId();
if (visitorId) url.searchParams.set("app_user_id", visitorId);
window.location.href = url.toString();STRIPE events, so nothing counts twice.Verify it works
A real purchase appears in Revenue, converted to your reporting currency, credited to the linked visit.
Events
| Superwall event | What MetricRaven records |
|---|---|
| initial_purchase | A payment (none for a free trial) and a new subscription, trialing for a trial |
| renewal | A renewal payment; the first paid renewal after a trial records the trial conversion (MetricRaven uses the trial state it stored, since Superwall can send is_trial_conversion false for a Stripe trial end) |
| non_renewing_purchase | A one-time payment |
| product_change | The subscription's new product; MRR waits for its next charge |
| cancellation | A scheduled cancellation at the expiration date; still live until then |
| uncancellation | The scheduled cancellation is cleared |
| refund | The refunded amount is taken off the payment; a revoked subscription ends |
| billing_issue | The subscription is past due |
| subscription_paused | Nothing yet: a Google Play pause starts at the period end |
| subscription_extended | Acknowledged, no change |
| expiration | The subscription ends (paused, for a Google Play pause) |
| transferred | The transferred purchases move to the receiving app user |
Paywall events
Superwall's webhooks carry no paywall views or closes. Forward them from the app's handleSuperwallEvent with the SDK: see Paywall events.
Test mode
Every Superwall event carries event_data.environment: SANDBOX for store sandbox purchases and web checkout in Stripe test mode, PRODUCTION otherwise. Turn on Test mode before connecting, and the connection records only SANDBOX events; a live connection records only PRODUCTION events. Superwall sends both to the same webhook, so give a test site its own webhook (a project can have several). Superwall sends no test events to V2 webhooks: test with a sandbox purchase.
- Test payments and subscriptions are stored marked as test data and count in that site's revenue, MRR and subscriptions. The provider's panel shows a Test mode badge, and the Revenue tab a Test mode notice.
- Test payments don't count toward your plan's monthly events and send no payment alerts.
- The mode is chosen when you connect. Replacing a key or secret keeps it; to switch between test and live, disconnect and connect again. Test data already recorded stays.
- Connect test mode to a separate test website, so test payments never sit next to real revenue. See Test mode.
Troubleshooting
- No events at all: Superwall tracks no revenue yet (Needs revenue tracking, or Stripe's keys shown as Missing under Integrations → Stripe). Connect App Store Connect, Google Play or Stripe there first.
- Signature rejected on the MetricRaven panel: the secret doesn't match the webhook. Rotate the secret in Superwall and paste the new one.
- Nothing arrives after a sandbox purchase: the connection is live and records only
PRODUCTIONevents. Connect a test site in Test mode (and the other way round). - A purchase arrives late: when Superwall doesn't know the buyer yet it holds the event for up to 48 hours, then sends it without a user. The revenue still counts, but can't be linked to a visit.
- Web checkout payments missing: with Stripe connected, they come from the Stripe import instead.
- Superwall removes any
Authorizationcustom header before delivery; MetricRaven relies only on the signature.
Details
- Purchase and renewal events add revenue in the purchase currency. Refund events reduce it; a cancellation is not a refund.
- Subscription events also record automatic lifecycle goals such as
trial_started,trial_converted,subscription_cancel_scheduledandsubscription_ended, attributed to the linked visitor. - This connection receives new events. It does not import your Superwall history.
- Live subscriptions and MRR: State from the webhook's purchase, renewal, cancellation, billing-issue, plan-change and expiration events. MRR is the price of the last paid purchase or renewal divided by its period (from its purchase and expiration dates). An introductory price leaves MRR unavailable until the first regular renewal, and a plan change until the new product's first charge. Superwall's webhook has no history: a subscription appears with its next event, and its amount with its next paid purchase or renewal. Amounts in other currencies convert at the latest ECB rates. See the Revenue dashboard.
- Redelivered events count once. If Superwall sits on top of RevenueCat, connect only one of them, so the same store purchase isn't recorded twice.