Atribución en tiempo real mediante webhooks
Los webhooks son callbacks HTTP que notifican a Insert Affiliate en el momento en que ocurre una compra en tu app. Esta cadena de notificaciones en tiempo real garantiza que los afiliados reciban el crédito al instante cuando sus usuarios referidos hacen compras dentro de la app, sin procesamiento por lotes, sin demoras y sin eventos perdidos.
La arquitectura de webhooks
El flujo en tiempo real funciona así:
- El usuario hace una compra en tu app
- La tienda de aplicaciones procesa el pago (Apple o Google)
- Tu servicio de verificación de compras (RevenueCat, Adapty o la integración directa con la tienda) recibe la notificación de la compra
- El servicio de verificación envía un webhook al endpoint de Insert Affiliate
- Insert Affiliate procesa el evento, lo asocia con una atribución de afiliado y calcula la comisión
- El panel del afiliado se actualiza y muestra la nueva conversión y las ganancias
Toda esta cadena se completa en segundos.
Tipos de eventos que debes configurar
Eventos de suscripción
- INITIAL_PURCHASE: primer pago de la suscripción (evento de conversión principal)
- RENEWAL: pago recurrente, que genera una comisión adicional en los modelos recurrentes
- CANCELLATION: el usuario canceló, lo que detiene la acumulación de comisiones futuras
- BILLING_ISSUE: el pago falló, así que la suscripción puede estar en periodo de gracia
- PRODUCT_CHANGE: el usuario subió o bajó de plan, así que la comisión se ajusta
- EXPIRATION: la suscripción expiró por completo después del periodo de gracia
Eventos de compra única
- NON_RENEWING_PURCHASE: desbloqueo único o compra no consumible
- CONSUMABLE_PURCHASE: IAP consumible (debe reportarse a través del SDK, no con webhooks de la tienda)
Eventos de reembolso
- REFUND: compra reembolsada, lo que activa la reversión de la comisión
Buenas prácticas de fiabilidad
Asegura la entrega
- Devuelve un estado 200 de inmediato al recibir el webhook, antes de procesarlo
- Procesa de forma asíncrona: primero confirma la recepción y luego ejecuta la lógica de negocio
- Supervisa las tasas de entrega: revisa cada semana los registros de entrega de webhooks en tu servicio de verificación de compras
Gestiona los fallos
- Configuración de reintentos: la mayoría de los emisores de webhooks reintentan las entregas fallidas con backoff exponencial. Asegúrate de que tu endpoint gestione bien los reintentos.
- Idempotencia: procesa cada evento exactamente una vez. Usa el ID de la transacción para detectar y omitir entregas duplicadas.
- Alertas: configura notificaciones para los fallos de entrega de webhooks, así puedes responder antes de que los afiliados noten que faltan comisiones.
Seguridad
- Verifica las firmas: la mayoría de los proveedores de webhooks firman sus payloads. Verifica las firmas para evitar eventos falsificados.
- Usa HTTPS: todos los endpoints de webhooks deben usar cifrado HTTPS.
- Restringe el acceso: si es posible, agrega a una lista de permitidos las direcciones IP del emisor de tus webhooks.
Webhooks directos de la tienda vs terceros
A través de RevenueCat/Adapty (recomendado):
- Un único endpoint de webhook gestiona tanto iOS como Android
- Formato de eventos normalizado entre plataformas
- Reintentos y supervisión de entregas integrados
- Menos complejidad de configuración
Directo desde Apple/Google:
- Apple Server Notifications V2: JWT firmados con eventos del ciclo de vida de la suscripción
- Google Real-Time Developer Notifications a través de Cloud Pub/Sub
- Más configuración, pero sin dependencia de terceros
- Los formatos distintos requieren una lógica de procesamiento separada
Cómo probar el pipeline de webhooks
- Compras en sandbox: haz compras de prueba y verifica que los webhooks lleguen a Insert Affiliate
- Cobertura de tipos de eventos: prueba cada tipo de evento: compra, renovación, cancelación, reembolso
- Tiempos: verifica que los eventos lleguen en segundos, no en minutos
- Coincidencia de la atribución: confirma que la compra corresponde al afiliado correcto
- Cálculo de la comisión: verifica que el monto de la comisión sea correcto
El panel de Insert Affiliate muestra los eventos de webhook entrantes y su estado de procesamiento, lo que facilita verificar que el pipeline funciona correctamente antes y después del lanzamiento.