RevenueCat Integration
RevenueCat webhooks handle ALL purchase and subscription events. No in-app purchase tracking code needed.
Why Webhooks, Not SDK Tracking#
- Captures subscription renewals even when the app is closed
- Handles cancellations, billing issues, and expirations automatically
- No client-side purchase event tracking code needed
- Single source of truth for all subscription lifecycle events
Setup#
- In RevenueCat → Project Settings → Integrations → Webhooks → click New.
- Set the webhook URL to:
https://your-domain.com/api/webhook/revenuecat/{appId}(copy the exact URL from Settings in the AppRefer dashboard). - Set the Authorization header: generate a webhook secret in AppRefer Settings → Integrations → RevenueCat.
- Enable all event types in the RevenueCat webhook configuration.
Link Device ID (Critical)#
CRITICAL: This is the most important step
You MUST set the
appreferId subscriber attribute on RevenueCat. Without it, purchase events from RevenueCat webhooks CANNOT be attributed to ad campaigns and will NOT be forwarded to ad networks. This single line of code is what connects your entire attribution pipeline to revenue.Call this immediately after AppRefer.configure() / AppReferSDK.configure(), before the user has any chance to make a purchase:
Flutter (Dart)
// 1. Configure AppRefer
final attribution = await AppReferSDK.configure(
AppReferConfig(apiKey: 'pk_live_...'),
);
// 2. REQUIRED: Link AppRefer to RevenueCat for purchase attribution
final deviceId = AppReferSDK.getDeviceId();
if (deviceId != null) {
await Purchases.setAttributes({'appreferId': deviceId});
}
// Without step 2, RevenueCat webhook events have no way to be
// matched back to the attributed device — purchases will be unattributed.How it works
When RevenueCat sends a webhook event (e.g., INITIAL_PURCHASE), AppRefer reads the
appreferId subscriber attribute from the webhook payload, looks up the device's attribution (including click IDs like fbclid/gclid/ttclid), and forwards the purchase to the relevant ad network. If appreferId is missing, the webhook event is logged but cannot be attributed or forwarded.Event Mapping#
| RevenueCat Event | AppRefer Event |
|---|---|
| INITIAL_PURCHASE | purchase |
| RENEWAL | purchase |
| PRODUCT_CHANGE | subscribe |
| NON_RENEWING_PURCHASE | purchase |
| CANCELLATION | cancellation |
| UNCANCELLATION | reactivation |
| BILLING_ISSUE | billing_issue |
| SUBSCRIPTION_PAUSED | pause |
| EXPIRATION | expiration |
| TRANSFER | transfer |
Ad Network Forwarding#
Only revenue-generating events trigger ad network forwarding:
| Event | Forwarded to Ad Networks |
|---|---|
| INITIAL_PURCHASE | Yes |
| RENEWAL | Yes |
| PRODUCT_CHANGE | Yes |
| NON_RENEWING_PURCHASE | Yes |
| CANCELLATION | No (analytics only) |
| UNCANCELLATION | No (analytics only) |
| BILLING_ISSUE | No (analytics only) |
| SUBSCRIPTION_PAUSED | No (analytics only) |
| EXPIRATION | No (analytics only) |
| TRANSFER | No (analytics only) |
Idempotency#
RevenueCat may deliver the same webhook event multiple times. AppRefer automatically deduplicates deliveries. Processed event IDs are retained for 30 days.