Notificaciones de webhook

Recibe notificaciones en tiempo real cuando se crean o desactivan afiliados en tu programa y cuando se contabiliza un referido dentro de la app. Los webhooks te permiten sincronizar automáticamente el estado de los afiliados con tus propios sistemas, sin necesidad de hacer polling.

Cómo funciona

Cuando se crea o se elimina un afiliado de tu empresa, o se contabiliza un referido dentro de la app, Insert Affiliate envía una solicitud HTTP POST a la URL de webhook que hayas configurado con los detalles del evento. Esto ocurre automáticamente en segundo plano y no retrasa la operación sobre el afiliado.

Configurar los webhooks

Ve a Configuración → pestaña Integraciones
1. Desplázate hasta la sección Notificaciones de Webhook
Introduce tu URL del webhook: debe usar HTTPS
Opcionalmente, introduce un Token Bearer: se enviará en el encabezado Authorization para que tu servidor pueda verificar que las solicitudes proceden realmente de Insert Affiliate
Haz clic en Guardar cambios

Sección Webhook Notifications en la configuración del panel de Insert Affiliate

Haz clic para ver a tamaño completo

Tu bearer token se almacena cifrado y nunca se muestra completo después de guardarlo.

Eventos de webhook

`affiliate.created`

Se envía cuando se añade un afiliado a tu empresa. Incluye todos los métodos de creación: añadir un afiliado manualmente desde el panel, aprobar una solicitud de registro autónomo o aceptar la solicitud de unión de un afiliado.

Payload:

{
  "event": "affiliate.created",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "occurred_at": "2026-03-18T12:00:00.000Z"
}

Campos:

Campo	Tipo	Descripción
`event`	string	Siempre `"affiliate.created"`
`affiliate_id`	string	Un identificador determinista del afiliado, derivado de su correo electrónico. Formato: `ia_` seguido de 8 caracteres hexadecimales. Es el mismo en todos los eventos del mismo afiliado.
`email`	string	La dirección de correo electrónico del afiliado
`deep_link`	string	La URL del deep link asignado al afiliado. Se incluye cuando se ha asignado un deep link (por ejemplo, al aprobar un registro autónomo o al aceptar una solicitud de unión). Puede ser una cadena vacía si todavía no se ha asignado ningún deep link.
`occurred_at`	string	Marca de tiempo ISO 8601 del momento en que ocurrió el evento

`affiliate.deactivated`

Se envía cuando se elimina un afiliado de tu empresa.

Payload:

{
  "event": "affiliate.deactivated",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "occurred_at": "2026-03-18T14:30:00.000Z"
}

Campos:

Campo	Tipo	Descripción
`event`	string	Siempre `"affiliate.deactivated"`
`affiliate_id`	string	El mismo identificador determinista que se envió en el evento `affiliate.created` de este afiliado. Úsalo para emparejar los eventos de creación y desactivación.
`email`	string	La dirección de correo electrónico del afiliado
`deep_link`	string	La URL del deep link que tenía asignada el afiliado en el momento de su eliminación. Cadena vacía si no se había asignado ningún deep link.
`occurred_at`	string	Marca de tiempo ISO 8601 del momento en que ocurrió el evento

`referral.created`

Se envía cuando ocurre algo que tu programa de referidos dentro de la app contabiliza como referido: una compra nueva, el evento que elegiste o una instalación, según tu configuración. Solo se envía cuando los referidos dentro de la app están activados, para los referidores que se unieron desde tu app.

Payload:

{
  "event": "referral.created",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "short_code": "a1b2c3d4",
  "trigger": "purchase",
  "referral_count": 3,
  "reward_status": "not_automatic",
  "occurred_at": "2026-09-18T12:00:00.000Z"
}

Campos:

Campo	Tipo	Descripción
`event`	string	Siempre `"referral.created"`
`affiliate_id`	string	El mismo identificador enviado en `affiliate.created` para este afiliado
`email`	string	La dirección de correo electrónico del referidor
`deep_link`	string	El enlace del referidor, o su código corto en las empresas que usan solo códigos cortos (Short Code Only)
`short_code`	string	El código corto del referidor
`trigger`	string	Lo que se contabilizó: `"purchase"`, `"event"` o `"install"`
`referral_count`	number	El nuevo total acumulado del referidor. Recompensa hasta este número; así nunca recompensarás dos veces y el siguiente envío pondrá al día cualquiera que se te haya pasado.
`reward_status`	string	Qué ocurrió con la recompensa automática cuando se registró el referido: `granted`, `not_automatic` (sin recompensa automática: recompénsalo tú si elegiste Yo los recompensaré personalmente), `waiting_for_account`, `waiting_for_codes` (a la espera de que Apple genere los códigos de oferta, o de que subas más códigos promocionales de Google Play; lo reintentamos cada hora), `failed` o `capped` (por encima del límite mensual, no recompenses este). Se envía una sola vez: una recompensa en espera que se otorga más tarde no envía un segundo webhook. Consulta la lista completa.
`occurred_at`	string	Marca de tiempo ISO 8601 del momento en que ocurrió el evento

Autenticación

Si configuraste un bearer token, cada solicitud de webhook incluye el encabezado:

Authorization: Bearer

Tu servidor debe verificar que este encabezado coincide con el token que configuraste en Insert Affiliate para asegurarse de que las solicitudes son legítimas.

Notas sobre el comportamiento

Fire-and-forget: el envío del webhook no bloquea la operación sobre el afiliado. Si tu endpoint no está disponible o devuelve un error, el afiliado se crea o se elimina con normalidad igualmente.
Solo HTTPS: las URL de webhook deben usar HTTPS por seguridad.
Tiempo de espera: las solicitudes caducan a los 10 segundos. Asegúrate de que tu endpoint responda con rapidez.
Sin reintentos: los webhooks fallidos no se reintentan. Si la fiabilidad es crítica, plantéate registrar los eventos recibidos por tu parte y conciliarlos periódicamente con el panel de Insert Affiliate.
ID de afiliado coherentes: el affiliate_id es determinista y se basa en el correo electrónico del afiliado. El mismo correo siempre generará el mismo affiliate_id, así que puedes emparejar de forma fiable los eventos created y deactivated.

Ejemplos de casos de uso

Sincroniza los afiliados con tu CRM: crea o archiva contactos automáticamente cuando los afiliados se unen o se van
Inicia flujos de onboarding: pon en marcha un flujo interno de onboarding cuando se aprueba a un nuevo afiliado
Actualiza tu propia base de datos: mantén tus registros de usuarios sincronizados con los cambios de estado de los afiliados
Alertas por Slack o correo electrónico: reenvía los eventos a un canal de notificaciones de tu equipo