<!--
Post*back* docs markdown
Canonical HTML: https://postback.sh/docs/superwall
Markdown URL: https://postback.sh/docs/superwall.md
Docs index: https://postback.sh/docs.md
Sitemap: https://postback.sh/sitemap.xml
LLM guide: https://postback.sh/llms.txt
-->

# Superwall

Forward Superwall webhook events to Post*back* so paywalls, trials, and subscription changes are attributed to the original install.

## Webhook endpoint

```
Host: api.postback.sh
Path: /v1/integrations/superwall/webhooks/{appId}
```

Paste the HTTPS URL for this host and path into Superwall → Settings → Integrations → Webhooks.

Replace `{appId}` with your Post*back* app ID. The dashboard integration page shows the full URL for the selected app.

## Authentication

Superwall signs webhooks using Svix. After creating the webhook in Superwall, open that webhook, copy its Signing Secret, and paste it into Post*back* under Integrations → Superwall.

Post*back* marks the integration verified after the first valid, signed webhook. Sandbox webhooks can verify the connection, but Post*back* does not create attributed events or outbound ad conversions from `environment=SANDBOX` deliveries.

## Event mapping

| Superwall event | Post*back* event |
|----------------|-----------------|
| initial_purchase | purchase |
| initial_purchase + periodType=TRIAL | start_trial |
| renewal, including isTrialConversion=true | subscribe |
| uncancellation | purchase |
| non_renewing_purchase | purchase |
| cancellation / expiration / billing_issue / product_change / subscription_paused | custom |

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 Post*back* event attribution.

## Required: postbackId user attribute

For webhooks to be matched to an attribution, you must set the `postbackId` user attribute in Superwall from the SDK.

## SDK snippets

Set the user attribute after the Post*back* SDK is configured. In React Native and Flutter, `getPostbackId()` is asynchronous, so await it before calling Superwall. See the Superwall docs page for platform-specific code snippets.

---

## Docs navigation

Use the Markdown URLs when reading the docs programmatically. Use the HTML URLs when you need the interactive docs UI.

- [Overview](https://postback.sh/docs) ([Markdown](https://postback.sh/docs.md)) — Introduction to Post*back*
- [Quickstart](https://postback.sh/docs/quickstart) ([Markdown](https://postback.sh/docs/quickstart.md)) — Get up and running in 5 minutes
- [React Native](https://postback.sh/docs/react-native) ([Markdown](https://postback.sh/docs/react-native.md)) — React Native / Expo SDK reference
- [iOS (Swift)](https://postback.sh/docs/ios-swift) ([Markdown](https://postback.sh/docs/ios-swift.md)) — Native Swift SDK reference
- [Android (Kotlin)](https://postback.sh/docs/android) ([Markdown](https://postback.sh/docs/android.md)) — Native Android SDK reference
- [Flutter](https://postback.sh/docs/flutter) ([Markdown](https://postback.sh/docs/flutter.md)) — Flutter plugin reference
- [RevenueCat](https://postback.sh/docs/revenuecat) ([Markdown](https://postback.sh/docs/revenuecat.md)) — Webhook integration for subscription attribution
- [Superwall](https://postback.sh/docs/superwall) ([Markdown](https://postback.sh/docs/superwall.md)) — Webhook integration for paywall attribution
- [Apple Search Ads](https://postback.sh/docs/apple-search-ads) ([Markdown](https://postback.sh/docs/apple-search-ads.md)) — Keyword and ad attribution
- [TikTok Ads](https://postback.sh/docs/tiktok-ads) ([Markdown](https://postback.sh/docs/tiktok-ads.md)) — Events API server-side event forwarding
- [Meta Ads](https://postback.sh/docs/meta-ads) ([Markdown](https://postback.sh/docs/meta-ads.md)) — In review