n8n flujos de trabajo

AI-School puede iniciar flujos de trabajo n8n mediante un webhook de producción. Esto es útil cuando deseas iniciar un proceso automatizado fuera de AI-School, por ejemplo, crear una tarea, actualizar un registro de CRM, iniciar un flujo de informes o enviar datos de formulario a otro sistema.

Ejemplo: artículo de noticias en el sitio web de la escuela

Supón que la escuela ha creado un flujo de trabajo en n8n que publica un artículo de noticias en el sitio web de WordPress de la escuela. En AI-School solo rellenas un breve texto, por ejemplo, unas cuantas frases sobre una semana de proyectos, un día deportivo o un día de puertas abiertas. Con ese texto inicias el flujo de trabajo en n8n.

El flujo de trabajo de n8n puede, por ejemplo:

1. Tomar el texto corto y convertirlo en un texto de concepto elegante con un nodo LLM y un prompt que se ajuste al tono de la escuela.
2. Generar una ilustración adecuada con un segundo nodo LLM, por ejemplo, en los colores de la escuela y en un estilo ilustrativo reconocible.
3. Preparar o publicar el texto e la imagen como entrada de blog en el sitio de WordPress.

Así trabajan AI-School y n8n juntos: en AI-School el usuario elige el flujo de trabajo y completa la información necesaria. Luego, n8n ejecuta los pasos automatizados y se asegura de que la noticia aparezca correctamente en el sitio web.

¿Qué hace esta integración?

Inicias un flujo de trabajo n8n desde la vista general de flujos de trabajo. Solo el webhook de producción, POST y Auth de cabecera son obligatorios. Los campos y las notificaciones de retorno desde n8n son opcionales y pueden configurarse de forma independiente.

• Si el flujo de trabajo no tiene campos, se invoca el webhook de inmediato.
• Si el flujo de trabajo tiene campos, primero se abre un formulario. El usuario rellena los campos y luego inicia el flujo con el botón.
• Los valores introducidos se envían como JSON en una solicitud POST al webhook de n8n.
• Sin notificaciones de retorno, AI-School solo confirma que el flujo de trabajo se ha iniciado y continúa en n8n. La ventana no muestra un spinner y puede cerrarse de inmediato.
• Si esto está habilitado en el registro, el flujo puede enviar de vuelta pasos intermedios o el final a AI-School.
• Si la aprobación está habilitada en el registro, el usuario puede tomar una decisión directamente en AI-School. n8n continúa desde el paso en espera.

Crear flujo de n8n en AI-School

Un administrador registra el flujo de la siguiente manera:

1. Ve a Asistentes.
2. Abre Flujos.
3. Elige Nuevo flujo n8n.
4. Introduce el nombre del flujo y la URL de producción de n8n.
5. Configura Autenticación de cabecera con un nombre de cabecera y un valor de cabecera secreto.
6. Marca bajo Notificaciones desde n8n solo las partes que realmente se hayan construido en este flujo n8n: progreso, aprobación y/o final del flujo.
7. Añade, si es necesario, los campos que deben enviarse en la solicitud POST.
8. Guarda el flujo.

Las tres opciones de retroalimentación están desactivadas por defecto. Si más adelante añades callbacks o un paso de aprobación en n8n, actualiza también el registro en AI-School. El diálogo sabrá así si solo debe mostrar una confirmación de inicio o si debe seguir esperando más señales.

Campos

• Los campos son opcionales.
• Cada campo tiene un nombre de campo y un tipo.
• Los tipos de campo admitidos son texto corto, texto largo, número, sí/no, fecha, una opción y varias opciones.
• Con Una opción y Varias opciones añades las opciones disponibles. Una opción se muestra como una lista de selección compacta; Varias opciones muestra casillas de verificación. El valor o los valores elegidos se envían en el cuerpo JSON.
• Los campos obligatorios deben completarse antes de que pueda iniciarse el flujo.
• El nombre del campo se convierte en la clave en el cuerpo JSON enviado a n8n.

Crear flujo compatible en n8n

1. Crea en n8n un nuevo flujo.
2. Añade como primer nodo un Webhook.
3. Da a este nodo exactamente el nombre Start workflow. Los ejemplos de más abajo usan este nombre.
4. Configura HTTP Method como POST.
5. En Authentication elige Header Auth y selecciona una credencial de Header Auth.
6. En esa credencial, introduce el mismo nombre de cabecera y valor secreto que en el flujo en AI-School.
7. Configura Respond o Response Mode en Immediately. La app recibirá entonces una confirmación de inicio exitosa de inmediato, mientras n8n continúa.
8. Copia la Production URL del nodo Webhook en el campo n8n production URL en AI-School. No uses la URL de prueba con /webhook-test/.
9. Activa el flujo en n8n.

Los datos de AI-School se encuentran en n8n bajo body. Por ello, los datos de integración se encuentran bajo body.integration. No elimines estos datos en un nodo Edit Fields-, Set- o Code. Los ejemplos a continuación los leen directamente desde el nodo Start workflow.

Ejemplo de la JSON body

Si defines campos con los nombres prompt, cliente, audiencias y fecha, n8n recibirá, por ejemplo, este cuerpo JSON. AI-School añade automáticamente el objeto integration.

{
  "prompt": "Haz un resumen breve de la solicitud.",
  "cliente": "Organización de ejemplo",
  "audiencias": ["empleados", "padres"],
  "fecha": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "token-temporal-para-este-ejercicio"
  }
}

El token de callback es válido para una ejecución. No lo guardes en logs, configuración fija u otros sistemas.

Opcional: enviar progreso y finalización

AI-School solo puede mostrar lo que devuelva n8n. Utiliza estos callbacks solo si has activado en el registro Progreso intermedio y/o Finalizar el flujo.

Configurar nodo HTTP Request

1. Añade un nodo HTTP Request y asígnale un nombre, por ejemplo, Notificar progreso.

2. Configura Method como POST.

3. Haz clic en URL en Expression.

4. Pega exactamente esta expresión:

   {{ $('Start workflow').first().json.body.integration.callbackUrl }}

5. En Authentication elige None. El token temporal se añadirá como header en el siguiente paso.

6. Activa Send Headers y añade estos dos encabezados:

   Name	Value
   Authorization	Bearer {{ $('Start workflow').first().json.body.integration.callbackToken }}
   Content-Type	application/json

7. Activa Send Body.

8. Elige Body Content Type: JSON y Specify Body: Using JSON.

9. Pega el siguiente JSON en el campo JSON:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "documento-creacion-iniciada",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "documento_crear",
    "label": "Crear documento"
  },
  "message": "El documento se está creando."
}

10. Elige Execute step mientras pruebas el flujo desde la app. El nodo debería devolver estado 200.

Copia este nodo HTTP Request para cada estado de notificación. En cada copia, cambia al menos eventId, step.id, step.label y message.

Configurar último callback

Si está activada la Finalizar el flujo, debe haber un último callback al final de cada ruta posible. Usa type: "completed" para éxito, type: "failed" para un fallo que gestionas tú y type: "rejected" cuando el usuario rechaza el flujo.

Para una ejecución exitosa, el body podría verse así:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "flujo-completado",
  "type": "completed",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "cierre",
    "label": "Flujo completado"
  },
  "message": "El flujo ha finalizado.",
  "output": {
    "resultado": "Breve descripción o enlace al resultado"
  }
}

Dentro de una misma ejecución utiliza un eventId distinto para cada callback. También siempre usa una etiqueta step.label clara: este texto lo ve el usuario en la ventana de ejecución.

Opcional: solicitar aprobación en la app

Configurar nodo Wait

1. Añade un nodo Wait en el lugar donde se necesita aprobación.
2. En Resume, elige On Webhook Call.
3. Configura HTTP Method como POST.
4. En Authentication elige Header Auth.
5. Selecciona la misma credencial de Header Auth que en el nodo Start workflow.
6. Coloca antes del nodo Wait una copia del nodo HTTP Request configurado anteriormente y llámalo Solicitar aprobación.
7. Usa en este nodo la misma URL dinámica y encabezados. Reemplaza solo el cuerpo JSON por:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "control-documento",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "control_documento",
    "label": "Controlar documento"
  },
  "approval": {
    "question": "¿Puede continuar el flujo?",
    "context": "Antes de continuar, revisa el documento generado.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Aprobar" },
      { "value": "reject", "label": "Rechazar" }
    ]
  }
}

Conecta Solicitar aprobación al nodo Wait. El usuario verá entonces los botones en AI-School. La URL de reanudación secreta no se muestra al navegador; el servidor envía la elección de forma segura al nodo Wait.

Procesar la elección tras Wait

1. Después del nodo Wait añade un nodo Switch.

2. Usa como valor a comprobar:

   {{ $json.body.decision }}

3. Crea, por ejemplo, una ruta para approve y otra para reject.

4. Haz que cada ruta termine con un callback correspondiente: completed, rejected o failed.

Un valor de elección puede contener solo letras, números, _ y -. La etiqueta puede contener texto legible.

Configurar la URL de callback de producción

La URL de callback de producción para AI-School es:

https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback

No pegues esta URL como texto fijo en cada nodo de callback. Elige en el campo URL del nodo HTTP Request la opción Expression y usa:

{{ $('Start workflow').first().json.body.integration.callbackUrl }}

AI-School proporciona con cada inicio la URL de producción correcta de forma automática. La URL fija anterior solo se utiliza para comprobar durante las pruebas que la expresión apunta a AI-School.

Las llamadas triggerCustomN8nWorkflow, triggerN8nWorkflow y resumeN8nWorkflow las invoca la propia app. No es necesario configurarlas en n8n.

Enviar errores inesperados

Un callback normal de failed solo funciona cuando el nodo HTTP Request alcanza ese estado. Para errores inesperados de nodos, utiliza también un Error Workflow central de n8n.

Crear un Error Workflow central

1. Crea en n8n un flujo separado llamado AI-School - errores de retorno.

2. Añade un nodo Error Trigger.

3. Después añade un nodo HTTP Request.

4. Configura Method como POST.

5. En URL utiliza esta URL de producción fija:

   https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowExecutionFailed

6. Elige Authentication: None.

7. Activa Send Headers y añade:

   Nombre	Valor
   n8n-handihow-name	elvalor secreto que recibes del administrador de la plataforma
   Content-Type	application/json

8. Activa Send Body, elige JSON y pega este cuerpo:

{
  "executionId": "{{ $json.execution.id }}",
  "workflowId": "{{ $json.workflow.id }}",
  "workflowName": "{{ $json.workflow.name }}",
  "lastNode": "{{ $json.execution.lastNodeExecuted }}",
  "message": "{{ $json.execution.error.message }}"
}

9. Activa el Error Workflow.
10. Abre la configuración del flujo de trabajo normal y selecciona en Error Workflow este nuevo Error Workflow.

Envía siempre al menos un callback de progreso con executionId: "{{ $execution.id }}" justo después de Start workflow. Así la app sabrá a qué ejecución pertenece un error n8n inesperado.

Restricciones importantes

• Solo se soportan disparadores webhook.
• Solo se soportan URLs de webhook de producción.
• Se rechazan las URLs de test de webhook con /webhook-test/.
• Solo se admite POST.
• Solo se admite autenticación genérica de cabecera.
• El valor de la cabecera se trata como secreto en la aplicación.
• Tokens de callback y URLs de reanudación se procesan solo en el servidor y no están disponibles directamente para los usuarios.
• El tenant se determina en el servidor a partir del usuario que inicia sesión, no a partir de un valor enviado por el navegador.

Solución de problemas

• 404 o webhook no registrado: activa el flujo en n8n y usa la URL de producción.
• Error de autenticación: verifica que el nombre de cabecera y el valor sean idénticos en ambos sistemas.
• Datos faltantes: verifica que los nombres de campo en la aplicación coincidan con las claves que espera n8n.
• Sin solicitud en n8n: verifica que el flujo comience con un disparador webhook y que use POST.
• La ventana de ejecución continúa girando: si activaste Finalizar el flujo, comprueba si n8n envía un último callback de completed, failed o rejected. Si no esperas notificaciones, desactiva las tres opciones en el registro.
• Sin progreso visible: verifica si Progreso intermedio está activado en el registro, o si el objeto integration se mantiene y si cada callback tiene un eventId único.
• Los botones de aprobación no funcionan: verifica la Wait node, resumeUrl, autenticación de cabecera y los caracteres permitidos en choices[].value.