Documentation

Superwall

Forward Superwall webhook events to Postback so paywalls, trials, and subscription changes are attributed to the install that triggered them. Setup takes about 10 minutes.

Requirements

  • The Postback SDK installed and configured in your app.
  • A Superwall account with admin access to add a webhook.
  • The webhook Signing Secret copied from the webhook you create in Superwall.
Event mapping
Superwall eventPostback event
initial_purchasepurchase
initial_purchase + periodType=TRIALstart_trial
renewal, including isTrialConversion=truesubscribe
uncancellationpurchase
non_renewing_purchasepurchase
cancellation / expiration / billing_issue / product_change / subscription_pausedcustom

Custom lifecycle events keep the raw Superwall type in the event name, for example superwall:cancellation. Signed webhooks carry subscription lifecycle and payment events. Postback does not install an app-side Superwall analytics delegate.

Add the webhook to Superwall

In Superwall, go to Settings → Integrations → Webhooks and add a new webhook with this URL:

https://api.postback.sh/v1/integrations/superwall/webhooks/{appId}

Replace {appId} with your Postback app ID. The dashboard integration page shows the full URL for the selected app.

Superwall signs webhooks using Svix. Postback verifies the signature using the signing secret stored under Integrations → Superwall in your dashboard. After creating the webhook in Superwall, open that webhook, use the copy button at the top right of the card to copy its Signing Secret, and paste it into Postback. No extra header configuration is needed on Superwall's side.

svix-id: msg_xxxxxxxx
svix-timestamp: 1234567890
svix-signature: v1,xxxxxxxx

Postback considers the integration connected as soon as the signing secret is saved. Incoming webhooks must still have a valid signature. Postback does not create attributed events or outbound ad conversions from environment=SANDBOX deliveries.

Use one subscription lifecycle webhook as the source of truth for each app. If RevenueCat already reports these transactions to Postback, keep RevenueCat connected and skip this Superwall webhook.

Identify Superwall with postbackId

For webhooks to be matched to an attribution, set the postbackId value as the Superwall user ID and keep it as a user attribute. Do this before any paywall can open or purchase can begin.

Set the identity after Postback is configured. Android apps must also enable passIdentifiersToPlayStore in the options used to configure Superwall. In React Native and Flutter, await the install ID before calling Superwall:

import { useEffect, useRef } from 'react';
import { useUser } from 'expo-superwall';
import { Postback } from 'postback-react-native';


export function PostbackSuperwallIdentity() {
  // Add options={{ passIdentifiersToPlayStore: true }} to your existing
  // <SuperwallProvider> so Android forwards this ID to Google Play.
  const { identify, update } = useUser();
  const didSyncPostbackId = useRef(false);
  const isSyncingPostbackId = useRef(false);


  useEffect(() => {
    if (didSyncPostbackId.current || isSyncingPostbackId.current) return;
    isSyncingPostbackId.current = true;


    void (async () => {
      try {
        const postbackId = await Postback.getPostbackId();
        if (!postbackId) return;


        await identify(postbackId);
        await update({ postbackId });
        didSyncPostbackId.current = true;
      } catch (error) {
        console.warn('Unable to sync the Postback ID to Superwall.', error);
      } finally {
        isSyncingPostbackId.current = false;
      }
    })();
  }, [identify, update]);


  return null;
}