Webhook-Based Affiliate Event Tracking for Real-Time IAP Attribution

Real-Time Attribution Through Webhooks

Webhooks are HTTP callbacks that notify Insert Affiliate the moment a purchase occurs in your app. This real-time notification chain ensures affiliates are credited instantly when their referred users make in-app purchases — no batch processing, no delays, no missed events.

The Webhook Architecture

The real-time flow works as follows:

1. User makes a purchase in your app
2. App store processes the payment (Apple or Google)
3. Your purchase verification service (RevenueCat, Adapty, or direct store integration) receives notification of the purchase
4. Verification service sends a webhook to Insert Affiliate's endpoint
5. Insert Affiliate processes the event — matches it to an affiliate attribution, calculates the commission
6. Affiliate's dashboard updates showing the new conversion and earnings

This entire chain completes in seconds.

Event Types to Configure

Subscription Events

• INITIAL_PURCHASE: First subscription payment — primary conversion event
• RENEWAL: Recurring payment — triggers additional commission for recurring models
• CANCELLATION: User cancelled — stops future commission accrual
• BILLING_ISSUE: Payment failed — subscription may be in grace period
• PRODUCT_CHANGE: User upgraded or downgraded — commission adjusts
• EXPIRATION: Subscription fully expired after grace period

One-Time Purchase Events

• NON_RENEWING_PURCHASE: One-time unlock or non-consumable purchase
• CONSUMABLE_PURCHASE: Consumable IAP (must be reported through SDK, not store webhooks)

Refund Events

• REFUND: Purchase refunded — triggers commission reversal

Reliability Best Practices

Ensure Delivery

• Return 200 status immediately upon receiving the webhook, before processing
• Process asynchronously — acknowledge receipt first, then handle the business logic
• Monitor delivery rates — check webhook delivery logs in your purchase verification service weekly

Handle Failures

• Retry configuration: Most webhook senders retry failed deliveries with exponential backoff. Ensure your endpoint handles retries gracefully.
• Idempotency: Process each event exactly once. Use the transaction ID to detect and skip duplicate deliveries.
• Alerting: Set up notifications for webhook delivery failures so you can respond before affiliates notice missing commissions.

Security

• Verify signatures: Most webhook providers sign their payloads. Verify signatures to prevent spoofed events.
• Use HTTPS: All webhook endpoints must use HTTPS encryption.
• Restrict access: If possible, allowlist the IP addresses of your webhook sender.

Direct Store Webhooks vs Third-Party

Through RevenueCat/Adapty (recommended):

• Single webhook endpoint handles both iOS and Android
• Normalised event format across platforms
• Built-in retry and delivery monitoring
• Less configuration complexity

Direct from Apple/Google:

• Apple Server Notifications V2: Signed JWTs with subscription lifecycle events
• Google Real-Time Developer Notifications via Cloud Pub/Sub
• More configuration but no third-party dependency
• Different formats require separate handling logic

Testing the Webhook Pipeline

1. Sandbox purchases: Make test purchases and verify webhooks arrive at Insert Affiliate
2. Event type coverage: Test each event type — purchase, renewal, cancellation, refund
3. Timing: Verify events arrive within seconds, not minutes
4. Attribution matching: Confirm the purchase matches the correct affiliate
5. Commission calculation: Verify the commission amount is correct

Insert Affiliate's dashboard shows incoming webhook events and their processing status, making it straightforward to verify the pipeline is working correctly before and after launch.