Guía de webhooks de Fansly: eventos en tiempo real sin polling

Si tu integración con Fansly consulta la API cada minuto para ver si hay mensajes, ventas o suscripciones nuevas, estás quemando créditos, añadiendo latencia y perdiendo eventos entre una consulta y otra. Los webhooks de Fansly le dan la vuelta al modelo: cada evento de Fansly llega a tu servidor en el momento en que ocurre, con firma criptográfica, reintentos automáticos y un contrato de idempotencia integrado para deduplicar con seguridad.

Esta guía explica qué eventos activan webhooks, cómo configurarlos en menos de cinco minutos, cómo gestionarlos con seguridad en producción y los casos de uso para agencias que justifican abandonar el polling.

Por qué los webhooks superan al polling en Fansly

El polling parece inofensivo: una tarea cron que llama a la API de Fansly cada minuto para preguntar «¿hay algo nuevo?». En realidad tiene tres problemas caros:

1. Costo: cada consulta consume créditos, haya eventos nuevos o no. Un polling «cada minuto» sobre 20 cuentas de creadores consume 28.800 llamadas al día. Con webhooks, la misma cobertura cuesta una fracción.
2. Latencia: entre consulta y consulta, los eventos se quedan esperando en la plataforma. Un whale deja una propina a las 9:00:15; tu scraper se da cuenta a las 9:01:00. En esos 45 segundos de diferencia es donde se cierran las ventanas para que el chatter haga el seguimiento.
3. Fiabilidad: el polling compite contra los límites de solicitudes. Las entregas de webhooks las pone en cola Fansly y se reintentan hasta que tu servidor confirma su recepción.

Los webhooks eliminan los tres. Un evento = una entrega HTTP = un crédito por cada 100 eventos.

Tipos de eventos de webhook de Fansly

Cada evento relevante en una cuenta de Fansly conectada activa un webhook. Los más habituales:

La lista completa se ve en el panel una vez que registras un endpoint. Se publican eventos nuevos con regularidad sin romper los handlers existentes.

Cómo configurar los webhooks de Fansly en 5 minutos

1. Abre el panel de Fansly API: ve a la sección Webhooks
2. Añade un endpoint: pega la URL de tu servidor (solo HTTPS; Fansly no entrega a HTTP)
3. Elige los eventos a los que suscribirte: empieza por message.received, sale.completed, subscription.renewed y subscription.expired. Amplía más adelante.
4. Copia el secreto de firma: guárdalo en tu entorno como FANSLY_WEBHOOK_SECRET
5. Haz una prueba desde el panel: Fansly envía un evento de prueba para que verifiques que tu servidor lo acepta y responde con un 200
6. Pasa a producción: activa el endpoint con el interruptor Active

Eso es todo. Tu servidor empieza a recibir los eventos en el momento en que ocurren.

Verificar las firmas de los webhooks de Fansly

Cada entrega incluye un encabezado X-Fansly-Signature. Verifícalo antes de procesar cualquier payload; de lo contrario, un atacante podría falsificar eventos.

import { createHmac } from 'crypto'
 
function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return signatureHeader === expected
}
 
// En tu handler:
if (!verifyWebhook(req.rawBody, req.headers['x-fansly-signature'], process.env.FANSLY_WEBHOOK_SECRET)) {
  return res.status(401).send('invalid signature')
}

Fíjate en el uso de rawBody: tienes que calcular el hash del cuerpo antes de parsear el JSON o de que algún middleware lo modifique. La mayoría de los frameworks web tienen un modo de cuerpo sin procesar (raw body) que debes activar.

Gestionar con seguridad los reintentos de los webhooks de Fansly

Fansly reintenta, con backoff exponencial, cualquier entrega que no devuelva una respuesta 2xx. Con una red inestable, tu servidor puede recibir el mismo evento entre 2 y 5 veces.

Deduplica con la clave de idempotencia que acompaña a cada evento:

const seen = new Set() // usa Redis o una base de datos si tienes varias instancias
 
async function handleWebhook(event) {
  if (seen.has(event.idempotencyKey)) {
    return // ya procesado, se omite
  }
  seen.add(event.idempotencyKey)
  await processEvent(event) // ahora ya es seguro ejecutar la lógica de negocio
}

Para casos de uso de bajo volumen (< 10.000 eventos al día por servidor), un Set en memoria es suficiente. En producción con varios workers, guarda las claves en Redis con un TTL de 24 horas.

Casos de uso para agencias: lo que los webhooks hacen posible de verdad

Los webhooks no son una comodidad para desarrolladores. Son la base de todas las automatizaciones que generan ingresos en una agencia.

Alertas de whales en tiempo real → atrapa las propinas en minutos

Suscríbete a tip.received, filtra los importes ≥ $100 y envíalos a un canal de Slack o al Telegram de los chatters. Resultado: los chatters contactan al fan mientras sigue en la conversación, no a la mañana siguiente, cuando la oportunidad ya se ha esfumado.

Secuencias de bienvenida → activa a los nuevos suscriptores en la primera hora

Suscríbete a subscription.created. Espera 1 hora. Envía un mensaje directo de bienvenida personalizado a través de la API de mensajería. Espera 24 horas. Haz el seguimiento con un PPV. Resultado: entre 3 y 5 veces más ingresos en la primera semana por cada nuevo suscriptor, frente a esperar a que un chatter lo contacte manualmente.

Recuperación de churn → recupera entre el 15% y el 25% de las suscripciones vencidas

Suscríbete a subscription.expired. Espera 7 días. Envía un mensaje directo personalizado con un código de descuento del endpoint de Promotions y un enlace de seguimiento. Resultado: miles de dólares de MRR recuperado gracias a un flujo de trabajo que funciona solo.

Asignación de chatters → pon a la persona adecuada con el fan adecuado

Suscríbete a message.received. Obtén el nivel de gasto del fan desde el endpoint de Fans. Asigna los fans de alto LTV a los chatters sénior, los fans nuevos a los encargados del onboarding y los fans inactivos a los especialistas en retención. Resultado: cada fan recibe el nivel de atención adecuado sin una clasificación manual.

Paneles de ingresos en tiempo real → finanzas deja de preguntar

Suscríbete a sale.completed y subscription.renewed. Envía los datos en streaming a BigQuery, Snowflake o una hoja de Google Sheets mediante n8n / Zapier / Make.com. Resultado: el equipo de finanzas ve llegar los ingresos a su panel en segundos, no en la conciliación de fin de mes.

Cumplimiento y monitoreo de contenido → detecta los problemas antes de que crezcan

Suscríbete a message.received. Pasa el texto por un clasificador de moderación (OpenAI Moderation API, Perspective API o tu propio modelo). Marca los mensajes problemáticos y envíalos al equipo de operaciones. Resultado: menos riesgo para la seguridad de la cuenta y cero horas de revisión manual.

Consejos de producción para los webhooks de Fansly

• Responde 200 rápido. Confirma la recepción y pon el evento en cola para procesarlo de forma asíncrona. Los handlers síncronos largos provocan timeouts y disparan reintentos.
• Registra cada entrega. Aunque tengas claves de idempotencia, guarda un registro del payload y de la respuesta para auditoría y depuración. El panel tiene una página Webhook Logs que muestra lo que ve Fansly desde su lado.
• Prueba los modos de fallo. Simula consultas lentas a la base de datos, caídas de API de terceros y fallos de almacenamiento. Tu handler nunca debería caerse por un solo evento defectuoso.
• Usa HTTPS con certificados válidos. Fansly no entrega a endpoints HTTP ni con TLS no válido. Configura Let's Encrypt o AWS ACM si todavía no lo tienes.
• Vigila el panel. La página Webhook Logs muestra cada intento de entrega, el número de reintentos y el estado final. Configura una alerta para cuando la tasa de fallos supere el 1% en una ventana de 5 minutos.

Precios de los webhooks de Fansly

Las entregas de webhooks cuestan 1 crédito por cada 100 eventos, normalmente entre 100 y 1000 veces menos que una cobertura equivalente con polling.

Una cuenta de creador con mucha actividad de fans (más de 5000 eventos al día entre mensajes, me gusta, propinas y suscripciones) cuesta unos 50 créditos al día en entregas de webhooks. La misma cobertura con polling cada minuto consumiría 1440 llamadas al día al costo estándar en créditos.

Planes y créditos incluidos:

• Basic: $69/mes: 20.000 créditos, 1 cuenta, acceso completo a webhooks
• Pro: $299/mes: 100.000 créditos, 5 cuentas, acceso completo a webhooks
• Enterprise: más de 100 cuentas: precios dinámicos desde solo $11,60 por cuenta, créditos personalizados

Los webhooks están incluidos en todos los planes de pago: no hace falta ningún nivel premium.

Consulta la página de precios completa para ver los créditos incluidos y las tarifas por exceso.

Preguntas frecuentes sobre los webhooks de Fansly

¿Qué diferencia hay entre el polling y los webhooks de Fansly? El polling significa que tu servidor le pregunta a la API de Fansly cada minuto (o cada segundo) si ha pasado algo nuevo. Los webhooks significan que Fansly avisa a tu servidor en el momento en que ocurre. A escala, los webhooks son entre 100 y 1000 veces más baratos, más rápidos y más fiables: no hay ninguna condición de carrera en la que se te escapen eventos entre una consulta y otra.

¿Son los webhooks de Fansly lo bastante fiables para producción? Sí. Cada entrega incluye una firma HMAC-SHA256 para verificarla, una clave de idempotencia para reintentar con seguridad y reintentos automáticos con backoff exponencial si falla. Hemos procesado más de 150 millones de eventos con garantías de entrega a la altura de los estándares empresariales.

¿Qué eventos de Fansly activan webhooks? Mensajes recibidos y enviados, ventas completadas, suscripciones creadas, renovadas y vencidas, propinas recibidas, PPV comprados, interacciones con publicaciones, indicadores de escritura, cambios de estado de la cuenta y más. La lista completa de eventos está disponible en el panel una vez que registras un endpoint.

¿Cómo gestiono con seguridad los reintentos de los webhooks de Fansly? Cada entrega de webhook incluye una clave de idempotencia única. Guarda las claves que ya has procesado (en Redis, en una base de datos o incluso en un set en memoria si el volumen es bajo) y descarta cualquier duplicado. Las entregas fallidas se reintentan con backoff exponencial hasta que tienen éxito o caducan.

¿Puedo usar los webhooks de Fansly sin escribir código? Sí. n8n, Zapier y Make.com ofrecen nodos disparadores de webhook. Pega la URL en el panel de Fansly API y tu flujo de trabajo no-code arranca en el momento en que se activa el evento: sin servidor, sin código y sin infraestructura que mantener.

Qué cambió en la versión de junio de 2025

Esta guía refleja la versión de Fansly API de junio de 2025, que introdujo:

• Webhooks de producción: entrega de eventos en tiempo real para mensajes, ventas, suscripciones, propinas, interacciones con publicaciones, indicadores de escritura y cambios de estado de la cuenta
• Integración con Make.com: la primera plataforma no-code con cobertura completa de Fansly API, con escenarios ya preparados para sincronizar transacciones y hacer seguimiento de enlaces
• Endpoints de gestión de contenido multimedia: sube fotos, videos y audio; organiza el contenido de la bóveda; crea listas de la bóveda
• Gestión de publicaciones: programa publicaciones con etiquetas, contenido multimedia, encuestas (normales y cuestionarios), objetivos de recaudación y fechas de caducidad
• Mensajería de chat avanzada: PPV, archivos multimedia adjuntos y etiquetas de creadores
• Formato de texto: negrita, cursiva, color y tamaño en publicaciones y mensajes

Sigue @onlyfansapi_updates en Telegram para estar al día de las últimas novedades.

¿Listo para dejar el polling? Regístrate gratis: incluye los primeros 100 créditos y no necesitas tarjeta de crédito.

¿Tienes preguntas? Escríbenos por correo electrónico o por Telegram.