flujos de n8n

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

Ejemplo: artículo de noticias en el sitio web de la organización

Supón que la organización ha creado un flujo de n8n que publica un artículo en el sitio web de WordPress. En AI-Public solo introduces un breve texto, por ejemplo, unas frases sobre una reunión, proyecto o anuncio público. Con ese texto inicias el flujo en n8n.

El flujo de n8n puede, por ejemplo:

1. A partir del texto corto, crear un texto conceptual limpio con un nodo LLM y una prompt que se ajuste al tono de la organización.
2. Crear una ilustración adecuada con un segundo nodo LLM, por ejemplo en los colores de la marca y en un estilo ilustrativo reconocible.
3. Preparar o publicar el texto y la imagen como una entrada de blog en el sitio de WordPress.

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

¿Qué hace esta integración?

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

• Si el flujo no tiene campos, se invoca el webhook de inmediato.
• Si el flujo tiene campos, primero se abre un formulario. El usuario completa 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 devoluciones, AI-Public solo confirma que el flujo ha comenzado y continúa en n8n. La ventana no muestra un spinner y se puede cerrar de inmediato.
• Si está activado en el registro, el flujo puede devolver pasos intermedios o el final a AI-Public.
• Si la aprobación está activada en el registro, el usuario puede tomar una decisión directamente en AI-Public. n8n continúa desde el paso en espera.

Crear flujo de n8n en AI-Public

Un administrador registra el flujo de la siguiente manera:

1. Ir a Asistentes.
2. Abrir Flujos.
3. Elegir Nuevo flujo n8n.
4. Introducir el nombre del flujo y la URL de producción de n8n.
5. Configurar Autenticación por cabecera con un nombre de cabecera y un valor secreto de cabecera.
6. Marcar bajo Devoluciones desde n8n solo las partes que realmente se construyeron en este flujo de n8n: progreso, aprobación y/o el final del flujo.
7. Añadir, si se desea, los campos que deben enviarse en la solicitud POST.
8. Guardar el flujo.

Las tres opciones de devolución vienen desactivadas por defecto. Si luego añades callbacks o una etapa de aprobación en n8n, actualiza también el registro en AI-Public. El cuadro de diálogo sabrá así si solo debe mostrar una confirmación de inicio o esperar señales adicionales.

Campos

• Los campos son opcionales.
• Cada campo tiene un nombre de campo y un tipo.
• Los tipos de campo compatibles son texto corto, texto largo, número, sí/no, fecha, una opción y múltiples opciones.
• En Una opción y Múltiples opciones agrega las opciones disponibles. Se mostrará una lista de selección compacta para Una opción; Múltiples opciones mostrará casillas de verificación. El valor o valores elegidos se envían en el cuerpo JSON.
• Los campos obligatorios deben completarse antes de iniciar el flujo.
• El nombre del campo se convierte en la clave en el cuerpo JSON que se envía a n8n.

Crear flujo compatible en n8n

1. Crea un nuevo flujo en n8n.
2. Añade como primera node un Webhook.
3. Asigna exactamente el nombre a esta node: Start workflow. Las expresiones de ejemplo a continuación usan este nombre.
4. Configura HTTP Method como POST.
5. Elige Authentication: Header Auth y utiliza el mismo nombre de cabecera y valor secreto que en AI-Public.
6. Configura Respond o Response Mode como Immediately.
7. Copia la Production URL al campo n8n production-url en AI-Public. No uses la URL de prueba con /webhook-test/.
8. Activa el flujo.

Los datos recibidos están bajo body; los datos técnicos de integración están bajo body.integration. No los elimines en un nodo Edit Fields-, Set- o Code.

Ejemplo del cuerpo JSON

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

{
  "prompt": "Maak een korte samenvatting van de aanvraag.",
  "klantnaam": "Voorbeeldorganisatie",
  "doelgroepen": ["inwoners", "medewerkers"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-public-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "tijdelijk-token-voor-deze-uitvoering"
  }
}

El token de callback pertenece a una única ejecución. No lo guardes en logs, configuración fija u otros sistemas.

Opcional: enviar progreso y cierre

AI-Public solo puede mostrar lo que devuelva n8n. Usa estas callbacks solo si en el registro has activado Notificar progreso intermedio y/o Notificar final de flujo.

Configura cada nodo callback así:

1. Elige Method: POST.

2. En URL haz clic en Expression y pega:

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

3. Elige Authentication: None.

4. Activa Send Headers y añade los siguientes encabezados.

5. Activa Send Body y elige Body Content Type: JSON y Specify Body: Using JSON.

Usa estos encabezados:

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

Por ejemplo, envía este mensaje cuando comienza un paso:

{
  "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": "Document maken"
  },
  "message": "Het document wordt gemaakt."
}

• Para cada evento dentro de la misma ejecución, usa un eventId único.
• Usa una etiqueta clara en neerlandés step.label; este texto se mostrará en la app.
• Si has activado Notificar final de flujo, al final envía siempre type: "completed", type: "failed" o type: "rejected".
• Si es completed, añade opcionalmente un objeto output con el resultado.
• Si es failed, envía un mensaje de error comprensible. La ejecución también se detiene en la app.

Opcional: solicitar aprobación en la app

Usa un nodo n8n Wait con On Webhook Call cuando el flujo solo pueda continuar tras una decisión. Enviar antes de la Wait una callback con type: "approval_required":

Configura la Wait node en Resume: On Webhook Call, HTTP Method: POST y Authentication: Header Auth. Selecciona la misma credencial de Header Auth que con Start workflow. Añade después de la Wait un nodo Switch y verifica allí {{ $json.body.decision }}.

{
  "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": "Document controleren"
  },
  "approval": {
    "question": "Mag de workflow doorgaan?",
    "context": "Controleer eerst het gegenereerde document.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Goedkeuren" },
      { "value": "reject", "label": "Afwijzen" }
    ]
  }
}

El usuario verá las opciones en la ventana de ejecución. Después de una elección, la Wait node recibirá entre otras cosas decision. Luego usa, por ejemplo, un nodo Switch para determinar la continuación correcta.

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

Configurar la URL de devolución de producción

La URL de devolución de producción para AI-Public es:

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

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

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

AI-Public proporciona así, en cada inicio, la URL de producción correcta. La URL fija anterior la puedes usar durante las pruebas para verificar que la expresión apunta a AI-Public y no a AI-School o AI-Corporate.

Las llamadas triggerCustomN8nWorkflow, triggerN8nWorkflow y resumeN8nWorkflow son invocadas por la propia app. No hace falta configurarlas en n8n.

Manejo de errores

Devuelve errores esperados con una callback de tipo failed. Para errores de nodos no esperados, crea además un flujo de Error central:

1. Crea un nuevo flujo con un nodo Error Trigger.

2. Añade luego un nodo HTTP Request con Method: POST.

3. En URL pon la URL de producción fija:

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

4. Elige Authentication: None y añade el header n8n-handihow-name con el valor secreto por defecto del administrador de la plataforma.

5. Elige un cuerpo JSON y pega:

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

6. Activa el flujo de errores.
7. Abre la configuración del flujo habitual y selecciónalo en Error Workflow.

Envíar inmediatamente después de Start workflow al menos una callback con executionId: "{{ $execution.id }}". Solo así AI-Public puede vincular un error inesperado a la ejecución correcta.

Limitaciones importantes

• Solo se soportan triggers mediante webhooks.
• Solo se soportan URLs de webhook de producción.
• Las URLs de webhook de prueba con /webhook-test/ se rechazan.
• Solo se soporta POST.
• Solo se soporta autenticación por cabecera genérica.
• El valor de la cabecera se trata como secreto en la aplicación.
• Los tokens de callback y las URLs de reanudar 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 autenticado, 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 exactamente iguales en ambos sistemas.
• Datos ausentes: verifica que los nombres de campos en la aplicación coincidan con las claves que espera n8n.
• Sin solicitud en n8n: verifica que el flujo comience con un webhook trigger y use POST.
• La ventana de ejecución permanece en funcionamiento: si has activado Notificar final de flujo, verifica que n8n envíe un callback final completed, failed o rejected. Si no esperas devoluciones, desactiva las tres opciones en el registro.
• Sin progreso visible: verifica si Notificar progreso intermedio está activado en el registro, o si el objeto integration se mantiene y cada callback tiene un eventId único.
• Los botones de aprobación no funcionan: verifica la Wait node, resumeUrl, autenticación por cabecera y los caracteres permitidos en choices[].value.