flujos de trabajo n8n

AI-School puede iniciar flujos de trabajo de n8n mediante un webhook de producción. Esto es útil cuando quieres iniciar un proceso automatizado fuera de AI-School, por ejemplo crear una tarea, actualizar un registro de CRM, iniciar un flujo de informes o reenviar datos de formularios 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 de 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 frases sobre una semana de proyectos, un día deportivo o una jornada de puertas abiertas. Con ese texto inicias el flujo de trabajo en n8n.

A continuación, el flujo de trabajo de n8n puede, por ejemplo:

1. Convertir el texto breve en un borrador limpio con un nodo LLM y un prompt que encaje bien con el tono de la escuela.
2. Generar una ilustración adecuada con un segundo nodo LLM, por ejemplo en los colores de la escuela y con un estilo ilustrativo reconocible.
3. Preparar o publicar el texto y la imagen como entrada de blog en el sitio web de WordPress.

Así es como AI-School y n8n trabajan juntos: en AI-School el usuario elige el flujo de trabajo y completa la información necesaria. Después, n8n ejecuta los pasos automatizados y se encarga de que el artículo de noticias llegue correctamente al sitio web.

¿Qué hace esta integración?

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

• Si el flujo de trabajo no tiene campos, el webhook se llama de inmediato.
• Si el flujo de trabajo sí tiene campos, primero se abre un formulario. El usuario completa los campos y después 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 vuelta, AI-School solo confirma que el flujo de trabajo se ha iniciado y que sigue ejecutándose en n8n. La ventana no muestra un spinner y puede cerrarse de inmediato.
• Si se ha activado durante el registro, el flujo de trabajo puede devolver pasos intermedios o el final a AI-School.
• Si se ha activado la aprobación durante el registro, el usuario puede hacer una elección directamente en AI-School. Luego n8n continúa desde el paso en espera.

Crear un flujo de trabajo n8n en AI-School

Un administrador registra el flujo de trabajo de la siguiente manera:

1. Ve a Asistentes.
2. Abre la pestaña Asistentes de flujo de trabajo.
3. En la tarjeta de la parte superior, haz clic en Nuevo flujo de trabajo y elige flujo de trabajo n8n.
4. Rellena el nombre del flujo de trabajo y la URL de producción de n8n.
5. Configura Autenticación de encabezado con un nombre de encabezado y un valor secreto de encabezado.
6. En Notificaciones de vuelta desde n8n, marca solo los elementos que realmente estén implementados en este flujo de trabajo n8n: progreso, aprobación y/o final del flujo de trabajo.
7. Añade, si es necesario, los campos que deban enviarse en la solicitud POST.
8. Guarda el flujo de trabajo.

Las tres opciones de notificación de vuelta están desactivadas por defecto. Si más tarde añades callbacks o un paso de aprobación en n8n, actualiza también el registro en AI-School. Así, el diálogo sabe 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 compatibles son texto corto, texto largo, número, sí/no, fecha, una opción y varias opciones.
• En Una opción y Varias opciones añades las opciones disponibles. Una opción se muestra como una lista desplegable 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 el flujo de trabajo pueda iniciarse.
• El nombre del campo se convierte en la key en el cuerpo JSON que se envía a n8n.

Crear un flujo de trabajo compatible en n8n

1. Crea un nuevo flujo de trabajo en n8n.
2. Añade como primer nodo un Webhook.
3. Dale exactamente el nombre Start workflow. Los ejemplos más abajo usan este nombre.
4. Pon HTTP Method en POST.
5. En Authentication, elige Header Auth y selecciona unas credenciales de Header Auth.
6. Introduce en esas credenciales el mismo nombre de encabezado y el mismo valor secreto que en el flujo de trabajo de AI-School.
7. Configura Respond o Response Mode en Immediately. Así la app recibe de inmediato una confirmación de inicio correcta, mientras n8n sigue trabajando.
8. Copia la Production URL del nodo Webhook al campo n8n production url en AI-School. No uses la URL de prueba con /webhook-test/.
9. Activa el flujo de trabajo en n8n.

Los datos de AI-School están en n8n bajo body. Por tanto, los datos de integración están bajo body.integration. No elimines estos datos en un nodo Edit Fields, Set o Code. Los ejemplos de abajo los leen siempre directamente desde el nodo Start workflow.

Ejemplo del cuerpo JSON

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

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

El token de callback pertenece a una sola ejecución. No lo guardes en registros, configuraciones fijas ni otros sistemas.

Opcional: devolver progreso y finalización

AI-School solo puede mostrar lo que n8n notifique de vuelta. Usa estos callbacks solo si en el registro has activado Notificar progreso intermedio y/o Notificar el final del flujo de trabajo.

Configurar el nodo HTTP Request

1. Añade un nodo HTTP Request y llámalo, por ejemplo, Notificar progreso.

2. Pon Method en POST.

3. En URL, haz clic 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á en el siguiente paso como encabezado.

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": "document-maken-gestart",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "Crear documento"
  },
  "message": "Se está creando el documento."
}

10. Elige Execute step mientras pruebas el flujo de trabajo desde la app. El nodo debe devolver un estado 200.

Copia este nodo HTTP Request para cada notificación de estado. En cada copia, ajusta como mínimo eventId, step.id, step.label y message.

Configurar el callback final

Si Notificar el final del flujo de trabajo está activado, al final de cada ruta posible debe haber un callback final. Usa type: "completed" en caso de éxito, type: "failed" para un error que gestionas tú mismo y type: "rejected" cuando el usuario rechaza el flujo de trabajo.

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

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

Dentro de una misma ejecución, usa un eventId distinto para cada callback. Usa siempre también un step.label claro: este texto es el que ve el usuario en la ventana de ejecución.

Opcional: pedir aprobación en la app

Configurar el nodo Wait

1. Añade un nodo Wait en el punto donde se necesite aprobación.
2. En Resume, elige On Webhook Call.
3. Pon HTTP Method en POST.
4. En Authentication, elige Header Auth.
5. Selecciona las mismas credenciales de Header Auth que en el nodo Start workflow.
6. Coloca antes del nodo Wait una copia del nodo HTTP Request configurado anteriormente y nómbralo Pedir aprobación.
7. Usa en este nodo la misma URL dinámica y los mismos encabezados. Reemplaza solo el cuerpo JSON por:

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

Conecta Pedir aprobación con el nodo Wait. Después, el usuario verá los botones en AI-School. La resume-url secreta no se entrega al navegador; el servidor envía la elección de forma segura al nodo Wait.

Procesar la elección después del nodo 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 adecuado completed, rejected o failed.

Un valor de elección solo puede contener letras, números, _ y -. La etiqueta sí puede contener texto normal 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. En el campo URL del nodo HTTP Request, elige Expression y usa:

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

Así, AI-School proporciona automáticamente la URL de producción correcta en cada inicio. La URL fija de arriba solo se usa para comprobar durante las pruebas si la expresión apunta a AI-School.

Las llamadas triggerCustomN8nWorkflow, triggerN8nWorkflow y resumeN8nWorkflow son invocadas por la propia app. No necesitas configurar esas URLs en n8n.

Enviar errores inesperados

Un callback normal failed solo funciona cuando el flujo de trabajo llega al nodo HTTP Request correspondiente. Para errores inesperados de los nodos, usa además un n8n Error Workflow central.

Crear un Error Workflow central

1. Crea en n8n un flujo de trabajo aparte con el nombre AI-School - errores enviar de vuelta.

2. Añade un nodo Error Trigger.

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

4. Pon Method en POST.

5. Introduce esta URL de producción fija en URL:

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

6. Elige Authentication: None.

7. Activa Send Headers y añade:

   Name	Value
   n8n-handihow-name	el valor secreto estándar que recibes del administrador de la plataforma
   Content-Type	application/json

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

{
  "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 este nuevo Error Workflow en Error Workflow.

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

Limitaciones importantes

• Solo se admiten webhooks.
• Solo se admiten URL de webhook de producción.
• Se rechazan las URL de prueba con /webhook-test/.
• Solo se admite POST.
• Solo se admite autenticación genérica por encabezado.
• El valor del encabezado se trata como secreto en la aplicación.
• Los tokens de callback y las resume-url solo se procesan del lado del servidor y no están disponibles directamente para los usuarios.
• El tenant se determina del lado del servidor a partir del usuario conectado, no a partir de un valor enviado por el navegador.

Solución de problemas

• 404 o webhook no registrado: activa el flujo de trabajo en n8n y usa la URL de producción.
• Error de autenticación: comprueba que el nombre y el valor del encabezado sean exactamente iguales en ambos sistemas.
• Datos faltantes: comprueba que los nombres de campo en la aplicación coincidan con las keys que n8n espera.
• No llega ninguna solicitud a n8n: comprueba que el flujo de trabajo empiece con un webhook trigger y use POST.
• La ventana de ejecución sigue cargando: si has activado Notificar el final del flujo de trabajo, comprueba que n8n envíe un último callback completed, failed o rejected. Si no esperas notificaciones de vuelta, desactiva las tres opciones durante el registro.
• No se ve progreso: comprueba que Notificar progreso intermedio esté activado durante el registro, que se conserve el objeto integration y que cada callback tenga un eventId único.
• Los botones de aprobación no funcionan: comprueba el nodo Wait, resumeUrl, la autenticación de encabezado y los caracteres permitidos en choices[].value.