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:
- A user clicks an affiliate link and is attributed to an affiliate partner
- The user installs the app and eventually makes a purchase
- The app store processes the payment and notifies your purchase verification service (RevenueCat, Adapty, or your direct integration)
- Your purchase verification service sends a webhook event to Insert Affiliate
- Insert Affiliate matches the purchase to the stored affiliate attribution
- The affiliate's commission is calculated and recorded
Each step in this chain relies on webhooks delivering the right data at the right time.
Webhook Event Reference
A complete integration handles the full subscription lifecycle. Here is how each event maps to commission behaviour:
| Event type | When it fires | Commission effect |
|---|---|---|
| Initial purchase | User's first subscription or in-app purchase | Primary attribution event; commission credited to the referring affiliate |
| Renewal | Each recurring billing cycle | Additional commission credited if renewal commissions are configured |
| Cancellation | Subscriber cancels future renewals | Stops future renewal credits; commissions already credited are not reversed |
| Refund | Purchase is refunded | Commission for that transaction is reversed |
| Trial conversion | Free trial converts to paid subscription | Commission credited — this is the trigger if your program commissions on paid conversion, not trial start |
Renewal commissions are credited and tracked automatically per event. Disbursement for any period requires a one-click approval from your Insert Affiliate dashboard — it is not automatic.
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:
- In RevenueCat's dashboard, navigate to Integrations
- Add a webhook endpoint pointing to Insert Affiliate's RevenueCat webhook URL
- Select the events you want to forward: initial purchase, renewal, cancellation, and billing issues
- 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:
- Make sandbox purchases on test devices
- Verify webhook events arrive at Insert Affiliate
- Confirm attribution matching works correctly
- Test edge cases: refunds, trial expirations, subscription upgrades
- Validate commission calculations against expected values
Before going live, run through this checklist:
- Sandbox initial purchase fires an event and credits commission to the correct affiliate
- A simulated renewal event is credited (if renewal commissions are configured)
- A sandbox refund reverses the commission for that transaction
- Delivering the same event twice does not double-credit the commission (idempotency check)
- Your endpoint returns
200on success and5xxon transient errors — not4xx, which signals a permanent failure and stops retry attempts
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 automatically — leaving only the final one-click payout approval for you to review and send.
Frequently Asked Questions
Does Insert Affiliate require RevenueCat, or can I integrate directly? Both options are available. Insert Affiliate supports direct integration with App Store Server Notifications V2 and Google Play Real-Time Developer Notifications, so you can connect without a third-party subscription management layer. RevenueCat and Adapty are also supported if you already use them.
How does Insert Affiliate know which affiliate to credit after a purchase? Attribution is matched using the affiliate's short code and company ID, which are passed as metadata on the purchase. Insert Affiliate reads those identifiers from the incoming webhook payload and credits the correct affiliate's account.
What happens if a webhook event is delivered more than once? Insert Affiliate processes events based on transaction identifiers, so duplicate deliveries don't result in double commissions. Your RevenueCat or app store integration handles retry logic on the sending side with exponential backoff.
Are renewal commissions paid out automatically? Renewals are tracked and credited automatically with each renewal event. Disbursement requires a one-click approval from your Insert Affiliate dashboard — it is not automatic, giving you a review step before funds are sent.