Webhook Integration Patterns for Mobile App Affiliate Programs

How Webhooks Power Affiliate Tracking

Webhooks are the backbone of modern mobile app affiliate tracking. They connect your purchase verification service to your affiliate platform in real time, ensuring that every qualifying purchase is attributed to the correct affiliate partner without manual intervention.

Understanding common webhook integration patterns helps you build a reliable, maintainable affiliate tracking pipeline.

The Basic Webhook Flow

The standard flow for affiliate tracking via webhooks follows this sequence:

1. A user clicks an affiliate link and is attributed to an affiliate partner
2. The user installs the app and eventually makes a purchase
3. The app store processes the payment and notifies your purchase verification service (RevenueCat, Adapty, or your direct integration)
4. Your purchase verification service sends a webhook event to Insert Affiliate
5. Insert Affiliate matches the purchase to the stored affiliate attribution
6. The affiliate's commission is calculated and recorded

Each step in this chain relies on webhooks delivering the right data at the right time.

Event Types You Need to Handle

A complete webhook integration handles several event types beyond the initial purchase:

Initial purchase events fire when a user makes their first subscription or in-app purchase. This is the primary conversion event that triggers affiliate attribution.

Renewal events fire each time a subscription renews. If your commission model includes recurring payments, renewal webhooks trigger additional commission calculations.

Cancellation events fire when a subscriber cancels. These can trigger commission adjustments or stop future recurring commissions.

Refund events fire when a purchase is refunded. Most affiliate programs claw back commissions on refunded transactions, and this webhook triggers that reversal.

Trial conversion events fire when a free trial converts to a paid subscription. For programs that commission on paid conversions, this is the actual trigger — not the trial start.

RevenueCat Webhook Integration

RevenueCat sends webhook events for all subscription lifecycle changes. To connect RevenueCat to Insert Affiliate:

1. In RevenueCat's dashboard, navigate to Integrations
2. Add a webhook endpoint pointing to Insert Affiliate's RevenueCat webhook URL
3. Select the events you want to forward: initial purchase, renewal, cancellation, and billing issues
4. Configure authentication headers if required

RevenueCat sends a JSON payload containing the customer identifier, product purchased, revenue amount, and transaction metadata. Insert Affiliate uses the customer identifier to match the purchase to the affiliate who referred that user.

Direct App Store and Google Play Webhooks

Insert Affiliate also integrates directly with the App Store (via Server Notifications V2) and Google Play (via Real-Time Developer Notifications). These direct integrations bypass the need for a third-party subscription management service.

For App Store Server Notifications, configure your App Store Connect account to send notifications to Insert Affiliate's endpoint. The notifications include subscription events in a signed JWT format that Insert Affiliate verifies and processes.

For Google Play, configure Real-Time Developer Notifications through Google Cloud Pub/Sub, with Insert Affiliate's endpoint as the subscriber.

Handling Webhook Failures

Webhooks can fail due to network issues, service outages, or payload format changes. Build resilience into your integration:

Retry logic: Most webhook providers (including RevenueCat) automatically retry failed deliveries with exponential backoff. Ensure your receiving endpoint returns appropriate HTTP status codes — 200 for success, 4xx for permanent failures, 5xx for temporary failures that should be retried.

Idempotency: Webhook events can be delivered more than once. Your processing logic should handle duplicate events gracefully by checking transaction identifiers before applying commission changes.

Monitoring: Set up alerts for webhook delivery failures. A silent failure in your webhook pipeline means missed affiliate attributions and potentially unpaid commissions — which erodes affiliate trust.

Testing Your Webhook Integration

Test webhooks in sandbox or staging environments before going live:

1. Make sandbox purchases on test devices
2. Verify webhook events arrive at Insert Affiliate
3. Confirm attribution matching works correctly
4. Test edge cases: refunds, trial expirations, subscription upgrades
5. Validate commission calculations against expected values

Insert Affiliate's dashboard shows incoming webhook events and their processing status, making it straightforward to debug integration issues during setup.

Best Practices

Keep your webhook integration clean by following these patterns: use HTTPS endpoints exclusively, validate webhook signatures to prevent spoofing, process events asynchronously to avoid timeout issues on the sender side, and log all incoming events for debugging and audit purposes.

A well-configured webhook integration runs silently in the background, accurately attributing every purchase to the right affiliate with zero manual effort.