Saltar al contenido principal

Integración n8n

Integración con n8n para automatización de workflows mediante webhooks personalizados por usuario.

Características​

  • ✅ Webhooks externos por usuario - Cada cuenta puede configurar su propia URL
  • ✅ Autenticación JWT opcional - Compatible con n8n HTTP Trigger usando JWT Auth
  • ✅ Sin autenticación - Opción para webhooks sin autenticación
  • ✅ Configuración desde UI - Interfaz en /configuracion
  • ✅ Botón de prueba integrado - Probar webhook directamente desde el dashboard
  • ✅ Gestión de secretos - Obtener y regenerar secretos JWT
  • ✅ Estado de envío - Ver último estado y error si existe

Configuración en Floutic​

1. Acceder a Configuración​

  1. Iniciar sesión en Floutic
  2. Ir a /configuracion
  3. Buscar sección "Webhooks Externos"

2. Configurar Webhook​

  1. URL del webhook: Debe ser HTTPS (requerido)
    • Ejemplo: https://tu-n8n-instance.com/webhook/floutic
  2. Habilitar/Deshabilitar: Toggle para activar o desactivar
  3. Método de autenticación:
    • JWT (recomendado): Usa autenticación JWT con secreto
    • None: Sin autenticación (menos seguro)

3. Obtener Secreto JWT​

Si eliges autenticación JWT:

  1. Hacer clic en "Obtener Secreto"
  2. Copiar el secreto (se muestra solo una vez)
  3. Guardarlo de forma segura

4. Regenerar Secreto​

Si necesitas regenerar el secreto:

  1. Hacer clic en "Regenerar Secreto"
  2. Se generará un nuevo secreto
  3. Actualizar la configuración en n8n con el nuevo secreto

5. Probar Webhook​

  1. Hacer clic en "Probar Webhook"
  2. Se enviará un evento de prueba
  3. Verificar en n8n que el webhook se recibió correctamente

Configuración en n8n​

1. Crear Workflow​

  1. Crear un nuevo workflow en n8n
  2. Añadir nodo "HTTP Trigger"
  3. Configurar el nodo:

2. Configuración del HTTP Trigger​

Configuración básica:

  • Path: /webhook/floutic (o el path que prefieras)
  • Response Mode: Last Node o When Last Node Finishes

Autenticación (si usas JWT):

  • Authentication: Generic Credential Type
  • Credential Type: Header Auth
  • Name: Authorization
  • Value: Bearer {secreto} (donde {secreto} es el secreto JWT de Floutic)

O usando JWT Auth (método recomendado):

  • Authentication: JWT
  • Key Type: Secret
  • Algorithm: HS256
  • Secret: (el secreto JWT de Floutic)

3. Procesar el Webhook​

El webhook recibirá un JSON con la siguiente estructura:

{
  "type": "notification_type",
  "timestamp": "2025-01-21T10:00:00Z",
  "data": {
    // Datos específicos según el tipo de notificación
  }
}

4. Conectar con Otros Nodos​

Después del HTTP Trigger, puedes:

  • Filtrar por tipo de notificación
  • Procesar los datos
  • Enviar a otros servicios (email, Slack, etc.)
  • Guardar en base de datos
  • Etc.

Tipos de Eventos​

Los webhooks envían los mismos eventos que las notificaciones del dashboard:

Eventos de Proyecto​

  • project_created - Proyecto creado
  • project_updated - Proyecto actualizado
  • project_status_changed - Estado de proyecto cambiado
  • project_expert_selected - Experto seleccionado
  • project_milestone_completed - Hito completado
  • project_milestone_approved - Hito aprobado
  • project_milestone_rejected - Hito rechazado
  • project_completed - Proyecto completado

Eventos de Aplicación​

  • application_received - Aplicación recibida
  • application_accepted - Aplicación aceptada
  • application_rejected - Aplicación rechazada

Eventos de Chat​

  • chat_message_received - Mensaje recibido
  • chat_file_uploaded - Archivo subido

Eventos de Pago​

  • payment_initiated - Pago iniciado
  • payment_held - Pago en depósito
  • payment_released - Pago liberado
  • payment_refunded - Pago reembolsado

Eventos de Disputa​

  • dispute_created - Disputa creada
  • dispute_resolved - Disputa resuelta

Eventos de Usuario​

  • user_registered - Usuario registrado
  • profile_verified - Perfil verificado
  • profile_updated - Perfil actualizado

Ejemplo de Payload​

{
  "type": "project_expert_selected",
  "timestamp": "2025-01-21T10:00:00Z",
  "data": {
    "project_id": 123,
    "project_title": "Automatizar Gestión de Pedidos",
    "expert_id": 45,
    "expert_name": "Carlos Méndez",
    "company_id": 12,
    "company_name": "TiendaOnline.es",
    "budget": 800.00,
    "currency": "EUR"
  }
}

Endpoints de API​

  • GET /api/users/me/webhook - Obtener configuración de webhook
  • PUT /api/users/me/webhook - Configurar webhook
  • GET /api/users/me/webhook/secret - Obtener secreto JWT actual
  • POST /api/users/me/webhook/secret - Regenerar secreto JWT
  • POST /api/notifications/webhook/test - Disparar evento de prueba

Seguridad​

Autenticación JWT​

  • Algoritmo: HS256
  • Secreto: Generado automáticamente por Floutic
  • Header: Authorization: Bearer {secreto}
  • Validación: El secreto se valida en cada request

HTTPS Obligatorio​

  • Todas las URLs de webhook deben ser HTTPS
  • Las URLs HTTP son rechazadas automáticamente

Rate Limiting​

  • Los webhooks respetan el rate limiting de la API
  • Si hay demasiados requests, se puede aplicar rate limiting

Troubleshooting​

El webhook no se recibe​

  1. Verificar que la URL sea HTTPS
  2. Verificar que el webhook esté habilitado
  3. Verificar la configuración en n8n
  4. Usar el botón "Probar Webhook" para verificar

Error de autenticación​

  1. Verificar que el secreto JWT sea correcto
  2. Verificar que el algoritmo sea HS256
  3. Verificar que el header sea Authorization: Bearer {secreto}
  4. Regenerar el secreto si es necesario

El webhook se recibe pero no procesa​

  1. Verificar la estructura del JSON recibido
  2. Verificar que el workflow en n8n esté activo
  3. Revisar los logs de n8n
  4. Verificar que el nodo HTTP Trigger esté configurado correctamente

El webhook se recibe con retraso​

  1. Verificar la conectividad de red
  2. Verificar que n8n esté ejecutándose
  3. Revisar los logs de Floutic para ver si hay errores
  4. Verificar el estado del webhook en /configuracion

Mejores Prácticas​

  1. Usar autenticación JWT - Más seguro que sin autenticación
  2. Regenerar secretos periódicamente - Por seguridad
  3. Probar webhooks regularmente - Usar el botón de prueba
  4. Manejar errores - Configurar manejo de errores en n8n
  5. Logging - Registrar eventos importantes en n8n
  6. Validación - Validar los datos recibidos antes de procesarlos

Documentación Completa​

Para más detalles sobre webhooks, consulta:

Referencias​