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. Other Superwall event types are stored as webhook receipts but ignored for Postback event attribution.

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, 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 marks the integration verified after the first valid, signed webhook. Sandbox webhooks can verify the connection, but Postback does not create attributed events or outbound ad conversions from environment=SANDBOX deliveries.

Set the postbackId user attribute

For webhooks to be matched to an attribution, set the postbackId user attribute in Superwall from the SDK. This links the Superwall user to the Postback install.

Set the attribute after Postback is configured. In React Native and Flutter, await the install ID before calling Superwall:

import { Postback } from 'postback-react-native';
import Superwall from '@superwall/react-native-superwall';


const postbackId = await Postback.getPostbackId();
if (postbackId) {
  Superwall.shared.setUserAttributes({ postbackId });
}