Realtime attributie via webhooks
Webhooks zijn HTTP-callbacks die Insert Affiliate op de hoogte brengen op het moment dat er een aankoop in je app plaatsvindt. Deze realtime meldingsketen zorgt ervoor dat affiliates direct worden gecrediteerd wanneer hun doorverwezen gebruikers in-app aankopen doen, zonder batchverwerking, zonder vertragingen en zonder gemiste events.
De webhook-architectuur
De realtime flow werkt als volgt:
- Gebruiker doet een aankoop in je app
- App store verwerkt de betaling (Apple of Google)
- Je dienst voor aankoopverificatie (RevenueCat, Adapty of een directe store-integratie) ontvangt een melding van de aankoop
- Verificatiedienst stuurt een webhook naar het endpoint van Insert Affiliate
- Insert Affiliate verwerkt het event, koppelt het aan een affiliate-attributie en berekent de commissie
- Dashboard van de affiliate wordt bijgewerkt met de nieuwe conversie en verdiensten
Deze hele keten is binnen enkele seconden afgerond.
Eventtypes om te configureren
Abonnementsevents
- INITIAL_PURCHASE: Eerste abonnementsbetaling (primair conversie-event)
- RENEWAL: Terugkerende betaling, die extra commissie oplevert bij terugkerende modellen
- CANCELLATION: Gebruiker heeft opgezegd, waardoor toekomstige commissie niet meer wordt opgebouwd
- BILLING_ISSUE: Betaling mislukt, dus het abonnement zit mogelijk in een respijtperiode
- PRODUCT_CHANGE: Gebruiker heeft geüpgraded of gedowngraded, dus de commissie wordt aangepast
- EXPIRATION: Abonnement volledig verlopen na de respijtperiode
Events voor eenmalige aankopen
- NON_RENEWING_PURCHASE: Eenmalige ontgrendeling of niet-verbruikbare aankoop
- CONSUMABLE_PURCHASE: Verbruikbare IAP (moet via de SDK worden gerapporteerd, niet via store-webhooks)
Refund-events
- REFUND: Aankoop terugbetaald, wat een terugboeking van de commissie activeert
Best practices voor betrouwbaarheid
Zorg voor aflevering
- Retourneer direct status 200 bij ontvangst van de webhook, vóór de verwerking
- Verwerk asynchroon: bevestig eerst de ontvangst en handel daarna de businesslogica af
- Monitor afleverpercentages: controleer wekelijks de afleverlogs van webhooks in je dienst voor aankoopverificatie
Ga om met fouten
- Retry-configuratie: De meeste webhook-afzenders proberen mislukte afleveringen opnieuw met exponential backoff. Zorg dat je endpoint retries netjes afhandelt.
- Idempotentie: Verwerk elk event precies één keer. Gebruik de transactie-ID om dubbele afleveringen te detecteren en over te slaan.
- Alerting: Stel meldingen in voor mislukte webhook-afleveringen, zodat je kunt reageren voordat affiliates ontbrekende commissies opmerken.
Beveiliging
- Verifieer handtekeningen: De meeste webhook-providers ondertekenen hun payloads. Verifieer handtekeningen om vervalste events te voorkomen.
- Gebruik HTTPS: Alle webhook-endpoints moeten HTTPS-versleuteling gebruiken.
- Beperk toegang: Zet indien mogelijk de IP-adressen van je webhook-afzender op een allowlist.
Directe store-webhooks vs. third-party
Via RevenueCat/Adapty (aanbevolen):
- Eén webhook-endpoint verwerkt zowel iOS als Android
- Genormaliseerd eventformaat op alle platforms
- Ingebouwde retry en monitoring van aflevering
- Minder complexe configuratie
Direct van Apple/Google:
- Apple Server Notifications V2: ondertekende JWT's met events uit de levenscyclus van het abonnement
- Google Real-Time Developer Notifications via Cloud Pub/Sub
- Meer configuratie, maar geen afhankelijkheid van een third party
- Verschillende formaten vereisen aparte verwerkingslogica
De webhook-pipeline testen
- Sandbox-aankopen: Doe testaankopen en controleer of webhooks bij Insert Affiliate aankomen
- Dekking van eventtypes: Test elk eventtype: aankoop, verlenging, opzegging, refund
- Timing: Controleer of events binnen seconden aankomen, niet binnen minuten
- Attributiekoppeling: Bevestig dat de aankoop aan de juiste affiliate wordt gekoppeld
- Commissieberekening: Controleer of het commissiebedrag klopt
Het dashboard van Insert Affiliate toont binnenkomende webhook-events en hun verwerkingsstatus, zodat je eenvoudig kunt controleren of de pipeline correct werkt, zowel vóór als na de lancering.