Cómo los webhooks hacen funcionar el seguimiento de afiliados
Los webhooks son la columna vertebral del seguimiento moderno de afiliados en apps móviles. Conectan tu servicio de verificación de compras con tu plataforma de afiliados en tiempo real, lo que garantiza que cada compra que califica se atribuya al afiliado correcto sin intervención manual.
Entender los patrones comunes de integración de webhooks te ayuda a construir un pipeline de seguimiento de afiliados confiable y fácil de mantener.
El flujo básico de un webhook
El flujo estándar para el seguimiento de afiliados mediante webhooks sigue esta secuencia:
- Un usuario hace clic en un enlace de afiliado y queda atribuido a un afiliado
- El usuario instala la app y, con el tiempo, hace una compra
- La tienda de aplicaciones procesa el pago y notifica a tu servicio de verificación de compras (RevenueCat, Adapty o tu integración directa)
- Tu servicio de verificación de compras envía un evento de webhook a Insert Affiliate
- Insert Affiliate asocia la compra con la atribución de afiliado almacenada
- Se calcula y se registra la comisión del afiliado
Cada paso de esta cadena depende de que los webhooks entreguen los datos correctos en el momento correcto.
Referencia de eventos de webhook
Una integración completa cubre todo el ciclo de vida de la suscripción. Así se relaciona cada evento con el comportamiento de las comisiones:
| Tipo de evento | Cuándo se dispara | Efecto en la comisión |
|---|---|---|
| Compra inicial | Primera suscripción o compra dentro de la app del usuario | Evento principal de atribución; la comisión se acredita al afiliado que refirió al usuario |
| Renovación | Cada ciclo de facturación recurrente | Se acredita una comisión adicional si las comisiones por renovación están configuradas |
| Cancelación | El suscriptor cancela las renovaciones futuras | Detiene los créditos por renovaciones futuras; las comisiones ya acreditadas no se revierten |
| Reembolso | Se reembolsa la compra | Se revierte la comisión de esa transacción |
| Conversión de prueba | La prueba gratuita se convierte en suscripción de pago | Comisión acreditada; este es el disparador si tu programa paga comisión por la conversión de pago y no por el inicio de la prueba |
Las comisiones por renovación se acreditan y se registran automáticamente por evento. El desembolso de cualquier periodo requiere una aprobación con un clic desde tu panel de Insert Affiliate. No es automático.
Tipos de eventos que debes manejar
Una integración completa de webhooks maneja varios tipos de eventos además de la compra inicial:
Los eventos de compra inicial se disparan cuando un usuario hace su primera suscripción o compra dentro de la app. Este es el evento de conversión principal que activa la atribución de afiliado.
Los eventos de renovación se disparan cada vez que una suscripción se renueva. Si tu modelo de comisiones incluye pagos recurrentes, los webhooks de renovación activan cálculos de comisión adicionales.
Los eventos de cancelación se disparan cuando un suscriptor cancela. Pueden activar ajustes de comisión o detener futuras comisiones recurrentes.
Los eventos de reembolso se disparan cuando se reembolsa una compra. La mayoría de los programas de afiliados recupera las comisiones de las transacciones reembolsadas, y este webhook activa esa reversión.
Los eventos de conversión de prueba se disparan cuando una prueba gratuita se convierte en suscripción de pago. Para los programas que pagan comisión por conversiones de pago, este es el disparador real, no el inicio de la prueba.
Integración de webhooks con RevenueCat
RevenueCat envía eventos de webhook para todos los cambios del ciclo de vida de la suscripción. Para conectar RevenueCat con Insert Affiliate:
- En el panel de RevenueCat, ve a Integrations
- Agrega un endpoint de webhook que apunte a la URL de webhook de RevenueCat de Insert Affiliate
- Selecciona los eventos que quieres reenviar: compra inicial, renovación, cancelación y problemas de facturación
- Configura los encabezados de autenticación si hace falta
RevenueCat envía un payload JSON que contiene el identificador del cliente, el producto comprado, el monto del ingreso y los metadatos de la transacción. Insert Affiliate usa el identificador del cliente para asociar la compra con el afiliado que refirió a ese usuario.
Webhooks directos de App Store y Google Play
Insert Affiliate también se integra directamente con App Store (mediante Server Notifications V2) y Google Play (mediante Real-Time Developer Notifications). Estas integraciones directas evitan la necesidad de un servicio externo de gestión de suscripciones.
Para App Store Server Notifications, configura tu cuenta de App Store Connect para que envíe notificaciones al endpoint de Insert Affiliate. Las notificaciones incluyen eventos de suscripción en un formato JWT firmado que Insert Affiliate verifica y procesa.
Para Google Play, configura Real-Time Developer Notifications a través de Google Cloud Pub/Sub, con el endpoint de Insert Affiliate como suscriptor.
Cómo manejar los fallos de webhooks
Los webhooks pueden fallar por problemas de red, caídas del servicio o cambios en el formato del payload. Incorpora resiliencia en tu integración:
Lógica de reintentos: la mayoría de los proveedores de webhooks (incluido RevenueCat) reintenta automáticamente las entregas fallidas con backoff exponencial. Asegúrate de que tu endpoint receptor devuelva los códigos de estado HTTP adecuados: 200 para éxito, 4xx para fallos permanentes y 5xx para fallos temporales que deben reintentarse.
Idempotencia: los eventos de webhook pueden entregarse más de una vez. Tu lógica de procesamiento debe manejar bien los eventos duplicados, comprobando los identificadores de transacción antes de aplicar cambios en las comisiones.
Monitoreo: configura alertas para los fallos de entrega de webhooks. Un fallo silencioso en tu pipeline de webhooks significa atribuciones de afiliados perdidas y posibles comisiones sin pagar, lo que erosiona la confianza de los afiliados.
Cómo probar tu integración de webhooks
Prueba los webhooks en entornos de sandbox o staging antes de salir a producción:
- Haz compras de sandbox en dispositivos de prueba
- Verifica que los eventos de webhook lleguen a Insert Affiliate
- Confirma que la asociación de atribución funcione correctamente
- Prueba los casos límite: reembolsos, vencimientos de prueba, mejoras de suscripción
- Valida los cálculos de comisión frente a los valores esperados
Antes de salir a producción, repasa esta lista de verificación:
- Una compra inicial en sandbox dispara un evento y acredita la comisión al afiliado correcto
- Un evento de renovación simulado se acredita (si las comisiones por renovación están configuradas)
- Un reembolso en sandbox revierte la comisión de esa transacción
- Entregar el mismo evento dos veces no acredita la comisión dos veces (comprobación de idempotencia)
- Tu endpoint devuelve
200cuando hay éxito y5xxante errores transitorios, no4xx, que indica un fallo permanente y detiene los reintentos
El panel de Insert Affiliate muestra los eventos de webhook entrantes y su estado de procesamiento, lo que facilita depurar los problemas de integración durante la configuración.
Buenas prácticas
Mantén limpia tu integración de webhooks siguiendo estos patrones: usa exclusivamente endpoints HTTPS, valida las firmas de los webhooks para evitar la suplantación, procesa los eventos de forma asíncrona para evitar problemas de timeout del lado del emisor y registra todos los eventos entrantes para depuración y auditoría.
Una integración de webhooks bien configurada funciona en silencio en segundo plano y atribuye con precisión cada compra al afiliado correcto de forma automática, de modo que solo te queda revisar y enviar la aprobación final del pago con un clic.
Preguntas frecuentes
¿Insert Affiliate requiere RevenueCat o puedo integrarme directamente? Ambas opciones están disponibles. Insert Affiliate admite la integración directa con App Store Server Notifications V2 y Google Play Real-Time Developer Notifications, así que puedes conectarte sin una capa externa de gestión de suscripciones. RevenueCat y Adapty también son compatibles si ya los usas.
¿Cómo sabe Insert Affiliate a qué afiliado acreditar después de una compra? La atribución se asocia mediante el código corto del afiliado y el ID de la empresa, que se pasan como metadatos en la compra. Insert Affiliate lee esos identificadores del payload del webhook entrante y acredita la cuenta del afiliado correcto.
¿Qué pasa si un evento de webhook se entrega más de una vez? Insert Affiliate procesa los eventos según los identificadores de transacción, así que las entregas duplicadas no generan comisiones dobles. Tu integración con RevenueCat o con la tienda de aplicaciones maneja la lógica de reintentos del lado del envío con backoff exponencial.
¿Las comisiones por renovación se pagan automáticamente? Las renovaciones se registran y se acreditan automáticamente con cada evento de renovación. El desembolso requiere una aprobación con un clic desde tu panel de Insert Affiliate. No es automático, lo que te da un paso de revisión antes de enviar los fondos.