Webhooks

Que son los webhooks

Los webhooks son notificaciones HTTP que los proveedores de pago envian a tu academia cuando ocurre un evento relevante, como un pago exitoso, una suscripcion cancelada o un reembolso. Didia procesa estos webhooks automaticamente para:

• Crear inscripciones cuando se confirma un pago.
• Activar y renovar suscripciones.
• Enviar emails transaccionales (bienvenida, confirmacion de compra).
• Disparar automatizaciones del CRM.
• Iniciar drip content si esta configurado en el curso.
• Registrar la transaccion en el historial de pagos.

URLs de webhook por proveedor

Configura las siguientes URLs en el panel de cada proveedor de pago. Reemplaza tu-academia con el slug de tu academia o tu dominio personalizado:

• Stripe: https://tu-academia.didia.io/api/webhooks/stripe
• MercadoPago: https://tu-academia.didia.io/api/webhooks/mercadopago
• Lemon Squeezy: https://tu-academia.didia.io/api/webhooks/lemonsqueezy
• Hotmart: https://tu-academia.didia.io/api/webhooks/hotmart

Eventos procesados por proveedor

Stripe

• checkout.session.completed — pago completado, se crea la inscripcion automaticamente.
• customer.subscription.created — nueva suscripcion activa.
• customer.subscription.updated — cambio de plan o renovacion de suscripcion.
• customer.subscription.deleted — suscripcion cancelada (acceso hasta fin del periodo).

MercadoPago

• payment.approved — pago aprobado, se crea la inscripcion.
• payment.refunded — reembolso procesado.

Lemon Squeezy

• order_created — compra completada exitosamente.
• subscription_created — nueva suscripcion activa.
• subscription_cancelled — suscripcion cancelada.

Hotmart

• PURCHASE_APPROVED — compra aprobada. Si el comprador no tiene cuenta en tu academia, se crea automaticamente con los datos de la compra y se inscribe en el curso correspondiente.
• PURCHASE_REFUNDED — reembolso procesado.

Para Hotmart, debes mapear tus productos a cursos de Didia desde Admin > Ajustes > Integraciones usando la tabla de external_product_mappings.

Verificacion de firma

Cada proveedor firma los webhooks con un secreto compartido para verificar que la notificacion es autentica. Didia verifica la firma automaticamente usando las variables de entorno correspondientes:

• STRIPE_WEBHOOK_SECRET — secreto del webhook de Stripe.
• MERCADOPAGO_WEBHOOK_SECRET — secreto del webhook de MercadoPago.
• LEMONSQUEEZY_WEBHOOK_SECRET — secreto del webhook de Lemon Squeezy.

Configura estos valores en tu archivo .env o variables de entorno de Vercel. Sin estos secretos, los webhooks seran rechazados por seguridad.

Reintentos y idempotencia

Si tu servidor no responde con un codigo 200, los proveedores reintentaran el webhook:

• Stripe: reintenta hasta 3 veces en 24 horas con backoff exponencial.
• MercadoPago: reintenta automaticamente varias veces.
• Lemon Squeezy: reintenta con intervalos crecientes.
• Hotmart: reintenta segun su politica interna.

Los handlers de Didia son idempotentes: si un webhook se recibe multiples veces (por reintentos), no se duplican inscripciones ni pagos. Cada evento se procesa una sola vez basandose en el ID unico de la transaccion.

Preguntas frecuentes

• ¿Necesito configurar webhooks manualmente?

  Si. Debes ir al panel de cada proveedor de pago y agregar la URL de webhook de Didia. Tambien debes configurar las variables de entorno con los secretos de firma. La conexion OAuth (Stripe Connect, MercadoPago) se hace desde el panel de Didia, pero los webhooks requieren configuracion adicional.

• ¿Como puedo probar que los webhooks funcionan?

  Stripe ofrece una herramienta de CLI (stripe listen) que reenvia eventos a tu URL local para pruebas. MercadoPago y Lemon Squeezy tienen herramientas similares en sus dashboards. Tambien puedes realizar una compra de prueba con un precio minimo.

• ¿Que pasa si Hotmart envia un webhook de un producto que no esta mapeado?

  Si el producto de Hotmart no esta mapeado a un curso en Didia, el webhook se recibe pero no se crea ninguna inscripcion. Se registra un log para que puedas identificar y mapear el producto posteriormente.

• ¿Los webhooks funcionan con dominios personalizados?

  Si. Si tienes un dominio personalizado configurado, puedes usar esa URL en lugar de tu-academia.didia.io. Ambas URLs funcionan para recibir webhooks.

• ¿Puedo recibir webhooks de multiples proveedores simultaneamente?

  Si. Puedes tener webhooks de Stripe, MercadoPago, Lemon Squeezy y Hotmart configurados al mismo tiempo. Cada proveedor tiene su propia URL de webhook y su propio secreto de firma. Didia procesa cada uno independientemente.