How to Connect Apple Ads to Superwall for Trial and Purchase Attribution

To connect Apple Ads to Superwall, keep acquisition attribution and subscription events as two separate inputs.

Apple AdServices identifies the campaign, ad group, and keyword associated with an eligible install. Apple Ads reporting supplies spend. Superwall supplies trial, purchase, renewal, and other subscription lifecycle outcomes.

A stable install ID carried as a Superwall user attribute joins those inputs without expecting a Superwall webhook to contain Apple campaign data that it does not send.

Apple renamed Apple Search Ads to Apple Ads in 2025. Superwall's current documentation and many search queries still use the former name.

The short answer

A complete Superwall attribution flow needs four parts:

Superwall also offers its own Apple Search Ads integration. That can make Apple attribution fields available in Superwall's client-side data and dashboard. It does not mean those fields are forwarded in Superwall webhooks.

The important Superwall webhook limitation

Superwall's Apple Search Ads integration stores Apple fields as reserved $asa_* user attributes. According to Superwall's current documentation, those fields are not included in webhook or third-party integration payloads.

This matters because the following design will not work reliably:

Apple Ads -> Superwall $asa_* fields -> Superwall purchase webhook -> external keyword ROAS report

The webhook can describe the purchase and include supported custom user attributes, but it is not a raw export of Superwall's Apple attribution fields.

If you need to export Superwall's native Apple data directly, Superwall documents reading it on the client. If you need a server-side revenue join, collect Apple attribution independently and pass only your stable join ID into Superwall.

Two valid architectures

Superwall-native Apple attribution

Use Superwall's native Apple Search Ads integration when the main goal is to see Apple acquisition context inside Superwall or access its Apple fields from the app.

This can be sufficient for paywall analysis inside Superwall. For an external warehouse or MMP, verify the export path before designing around it because $asa_* attributes do not travel through webhook payloads.

Postback plus Superwall

Use this path when the report needs Apple spend, install attribution, and Superwall subscription outcomes in one server-side model.

The data flow is:

1. Postback creates an install ID and collects AdServices attribution.
2. The app saves that ID to Superwall as postbackId.
3. Superwall sends a signed lifecycle webhook containing the custom user attribute.
4. Postback attaches the event to the attributed install.
5. The Apple Ads reporting connection adds spend, impressions, and taps.

Superwall remains the subscription-event source. Postback owns the Apple attribution and reporting join.

Step 1: Configure Apple Ads attribution in the app

Install and configure the Postback SDK at app startup. On iOS, the SDK requests the AdServices token and registers the installation.

AdServices tokens expire after 24 hours. Collect and send the token during the early app experience rather than waiting for the user to reach a paywall or start a trial.

Requesting the standard AdServices attribution token does not itself require an App Tracking Transparency prompt or IDFA access. Returned fields still depend on Apple's eligibility and privacy rules, so a report must tolerate missing keyword detail.

Step 2: Set the postbackId Superwall user attribute

Once Postback has registered the install, copy its ID into Superwall as a custom user attribute.

For a native iOS app:

import PostbackSDK
import SuperwallKit

if let postbackId = Postback.shared.getPostbackId() {
  Superwall.shared.setUserAttributes([
    "postbackId": postbackId,
  ])
}

Call this after both SDKs are configured and the ID is available. Superwall merges new user attributes with existing ones, so there is no need to recreate the full attribute map.

Use the exact key postbackId. Treat it as an attribution join key, not a place for a secret or personal profile data.

The desired identity chain is:

Postback install -> Superwall user attribute -> signed Superwall webhook -> original Postback install

Without this chain, the purchase can be valid while its Apple campaign remains unknown.

Step 3: Add the Superwall webhook

In Superwall, open Settings -> Integrations -> Webhooks and create a webhook for the Postback app:

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

Replace {appId} with the app ID shown in Postback.

Superwall sends webhooks through Svix. Copy the webhook's signing secret from Superwall and save it in Postback -> Integrations -> Superwall. No custom authorization header is required on the Superwall side.

Each delivery includes Svix headers such as:

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

Postback verifies the signature against the raw request body. This protects the endpoint from fabricated purchase events and detects payload modification.

If you build a receiver yourself, do not parse and re-serialize the JSON before verification. Signature libraries expect the original body bytes, the message ID, the timestamp, and the signature header.

Step 4: Connect Apple Ads reporting

AdServices supplies campaign identifiers for an attributed install, but it does not include cost. Connect Apple Ads reporting in Postback to import spend, taps, and impressions.

The Apple Ads API vs AdServices guide explains why the two sources are complementary. If you are building your own reporting store, the Apple Ads export guide covers API, CSV, Power BI, PostgreSQL, and Redshift options.

Keep organization, campaign, ad group, and keyword IDs as the join keys. Names are useful display labels but can change after the original acquisition.

Step 5: Understand the event mapping

Postback currently maps the main Superwall lifecycle events as follows:

The signed webhook carries subscription lifecycle and payment events. Postback does not install an app-side Superwall analytics delegate as part of this integration, so do not assume every paywall interaction is automatically copied into Postback.

For revenue reporting, preserve the product, price or proceeds field used, currency, period type, transaction context, and whether a renewal is a trial conversion.

Step 6: Choose one transaction source of truth

Many apps use Superwall to render paywalls and RevenueCat to manage purchases. In that setup, both vendors may know about the same subscription transaction.

Do not send both lifecycle streams into the same attribution report unless you have a deliberate deduplication model.

Use this rule:

• If RevenueCat is the authoritative transaction and entitlement system, use the RevenueCat lifecycle webhook.
• If Superwall is the selected source for subscription lifecycle events, use the Superwall webhook.
• Keep Superwall paywall experimentation separate from transaction attribution when RevenueCat owns the purchase truth.

The RevenueCat keyword ROAS guide covers the alternative setup.

How keyword-level trial and purchase reporting works

After the join is live, group Superwall outcomes by the acquisition fields stored on the Postback install.

A useful Apple Ads report includes:

For a free-trial app, keep three states visible:

• Active: still inside the trial window.
• Mature: the trial has ended and the initial paid outcome can be observed.
• Revenue-mature: the cohort has reached the chosen revenue window, such as day 30 or the first renewal.

Do not count an active trial as a failed purchase. Compare keywords at the same cohort age and credit later renewals back to the original acquisition cohort.

Validation sequence

Test one link at a time:

1. Install a build with the Postback SDK configured.
2. Confirm a non-empty Postback ID is created.
3. Confirm Superwall's user attributes contain postbackId.
4. Save the correct Svix signing secret in Postback.
5. Send a Superwall test webhook and confirm the signature is accepted.
6. Confirm a controlled production transaction contains the custom user attribute.
7. Confirm the event attaches to the original install.
8. Confirm Apple attribution appears when Apple claims the install.
9. Confirm Apple Ads spend imports for the same organization and reporting period.
10. Reconcile one mature campaign or keyword cohort.

Superwall sandbox deliveries are useful for checking connectivity, but Postback does not create attributed production events or outbound ad conversions from environment=SANDBOX payloads. Finish with a controlled production check.

Common problems

The webhook is accepted but the event is unattributed

Inspect data.userAttributes.postbackId. A valid signature proves the sender, not the identity join.

Signature verification fails

Confirm the signing secret belongs to the exact Superwall webhook, and verify against the raw request body with all three Svix headers.

Apple fields are absent from the webhook

This is expected for Superwall's reserved $asa_* attributes. Collect Apple attribution separately or use Superwall's documented client-side access path.

The Apple install has no keyword

Search Match can produce a valid attribution without a named keyword. Keep it as a separate reporting bucket.

Purchase revenue appears twice

Check whether RevenueCat and Superwall are both reporting the same transaction. Keep one lifecycle source of truth.

ROAS looks weak for the newest cohorts

The trial or refund window may still be open. Use the free-trial ROAS workflow before reallocating budget.

When this setup makes sense

The joined setup is useful when Apple Ads decisions depend on downstream economics rather than paywall views alone:

• Cost per trial by keyword.
• Mature trial-to-paid conversion by campaign.
• Cost per paid subscriber.
• Initial-purchase and renewal revenue.
• Refund-adjusted ROAS.
• Comparable reporting when another channel is added.

If you only need Apple context in Superwall's own dashboard, start with its native integration. If you need a server-side join to spend and later lifecycle events, use the stable identity flow.

For the maintained version, follow the Postback Superwall setup to add the user attribute and signed webhook.

Sources

• Superwall webhooks - Current lifecycle payloads, revenue fields, environments, and user attributes
• Verify Superwall webhooks - Current Svix signature verification requirements
• Superwall user attributes - Current setUserAttributes behavior
• Extract Apple Search Ads data from Superwall - Current $asa_* availability and webhook limitation
• Apple AdServices - Current Apple Ads install attribution framework
• Postback Superwall integration - Current postbackId, signing-secret, webhook, and event-mapping setup