# Connect Superwall

> Receive Superwall purchase, renewal, refund and subscription events through a signed webhook, from apps and web checkout.

Source: https://metricraven.com/docs/superwall  
Markdown: https://metricraven.com/docs/superwall.md  
Section: Revenue

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

1. **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.

2. **Open Settings → Integrations → Superwall in MetricRaven**

   Turn on [Test mode](https://metricraven.com/docs/superwall#test-mode) first if this site should record sandbox purchases only. Copy the webhook URL.

3. **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.

4. **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.

5. **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](https://metricraven.com/docs/identify-users): 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.

```swift title="iOS (Swift)"
// 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])
}
```

```kotlin title="Android (Kotlin)"
// 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))
}
```

```typescript title="React Native / Expo"
// 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 });
```

```dart title="Flutter"
// 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:

```bash
# 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.

```javascript
// 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();
```

> **Note:** Web checkout charges run through your own Stripe account. If Stripe is also connected to this site, MetricRaven imports them from Stripe and skips Superwall's `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](https://metricraven.com/docs/paywall-events#app-superwall).

## 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](https://metricraven.com/docs/connect-payment-provider#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 `PRODUCTION` events. Connect a test site in [Test mode](https://metricraven.com/docs/superwall#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 `Authorization` custom 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](https://metricraven.com/docs/goals-funnels#payment-provider-goals) such as `trial_started`, `trial_converted`, `subscription_cancel_scheduled` and `subscription_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](https://metricraven.com/docs/revenue-dashboard#mrr-by-provider).
- 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.
