Connect Superwall

Connect Superwall so FounderHQ records the purchases your paywalls make. It takes your app's store identity and the signing secret Superwall gives you. Allow about five minutes.

Before you start

You need a FounderHQ brand, the FounderHQ SDK in your app (iOS or React Native), and Superwall handling your purchases.

Using Superwall with RevenueCat? Connect RevenueCat instead

When RevenueCat manages the subscriptions and Superwall runs in observer mode, RevenueCat sees every purchase and Superwall's own webhooks may not fire. Connect RevenueCat and stop here — one app connects once.

What you are deciding

Superwall reports purchases it did not charge, and FounderHQ takes Superwall at its word. That is the same trust it extends to RevenueCat, and it is enough to see your revenue, your channels, and your MRR from day one. Three things are worth knowing before you connect.

Refunds arrive as negative amounts, and FounderHQ subtracts them. Superwall has no separate refund event: a give-back shows up as a negative amount on whichever event carries it, and FounderHQ reads the sign, not the label.

If Superwall misses an event, it is gone. There is no way to ask Superwall to resend an event you never received, and no history to catch up from. Superwall retries a failed delivery for you, so this is rare — but when it happens, that purchase stays missing.

The direct store connections are stronger. Apple App Store and Google Play are signed by the stores themselves and can fill in history. Connect them where you can. If you add one later for this app, it takes over the money automatically — see below.

Create the connection in FounderHQ

In FounderHQ, open Settings → Integrations → Revenue. Choose the brand, then Superwall. Read the screen, choose Continue, and name the app: the App Store bundle ID, the Google Play package name, or both — whichever stores Superwall sells through.

Those names also reserve the app. If this app already reports to FounderHQ through RevenueCat or a direct store connection, FounderHQ refuses the second connection and names the one that holds it. Two reporters would count every purchase twice.

FounderHQ gives you a webhook address:

https://app.getfounderhq.com/api/hooks/payments/superwall/CONNECTION_ID

Add the webhook in Superwall

In Superwall, open Integrations → Webhooks and add an endpoint with that address. Select all nine events:

initial_purchase       renewal              non_renewing_purchase
product_change         cancellation         uncancellation
billing_issue          subscription_paused  expiration

Superwall shows a signing secret starting with whsec_. Copy it back into FounderHQ and save.

Pass the FounderHQ token on every purchase

FounderHQ needs one value to know which visitor bought:

const prepared = await founderhq.preparePurchase({ source: "app_store" });
// 1. Superwall forwards user attributes on every webhook.
Superwall.shared.setUserAttributes(["fhq_visitor": prepared.appAccountToken])
// 2. Pass the same value to StoreKit as appAccountToken, so Apple returns it
//    too — a direct App Store connection reads it from there.

Both carry the same UUID, and either one is enough. See mobile purchase claims for the full flow, including accounts.

What FounderHQ records

Superwall reports	FounderHQ records
App Store purchases	Superwall's amount and currency
Google Play purchases	Superwall's amount and currency
Stripe purchases	Ignored — connect Stripe
Refunds	The negative amount on the event
Lifecycle events	Cancellations, pauses, billing issues, expirations move state only

The price Superwall shows on its own dashboard is converted to US dollars and its proceeds are estimated. FounderHQ never uses either. It reads only the amount in the currency your customer actually paid.

Two more rules worth knowing:

Family Sharing. A family member's renewal arrives at zero. It updates the subscription and adds no revenue.
Refunds for purchases FounderHQ never saw. If a refund arrives for a purchase from before you connected, FounderHQ records the refund on the connection but does not subtract it — the purchase it reverses was never in your totals, so subtracting it would undercount your revenue.

Stripe. Connect Stripe directly. Superwall's Stripe events carry no charge reference, so FounderHQ cannot tell them apart from the ones Stripe already sends, and recording both would double your totals.

Adding a store connection later

This is the upgrade. Connect Apple App Store or Google Play for this app whenever you are ready. FounderHQ allows it, and from that moment the store owns the money:

The store's amounts, taxes, and dates replace Superwall's.
Superwall stays connected. Its events are kept as evidence and add nothing to your totals, so nothing is counted twice during the switch.
Everything already recorded stays in your reports.

The reverse is not allowed: once a store connection owns an app, FounderHQ refuses a second reporter for it. Disconnect the store connection first if you really want to go back.

Verify

Save the signing secret. The connection shows Waiting for test.
Make a purchase in your app. A TestFlight purchase works.
The connection shows Connected, and the purchase appears in Revenue with the channel that brought the customer.

Superwall has no send-a-test-event button, so a real purchase is what finishes setup. This is the one connector that cannot turn on before your first sale.

What you are deciding

Create the connection in FounderHQ

Add the webhook in Superwall

Pass the FounderHQ token on every purchase

What FounderHQ records

Adding a store connection later

Verify

Troubleshoot

Amounts look different from Superwall's dashboard

The connection shows "This endpoint only accepts production events."

Nothing arrives at all

Purchases arrive without a channel

On this page