fluxos de trabalho n8n

A AI-School pode iniciar fluxos de trabalho n8n através de um webhook de produção. Isso é útil quando você quer iniciar um processo automatizado fora da AI-School, por exemplo, criar uma tarefa, atualizar um registro de CRM, iniciar um fluxo de relatórios ou encaminhar dados de formulário para outro sistema.

Exemplo: artigo de notícias no site da escola

Suponha que a escola tenha criado um fluxo de trabalho n8n que publica um artigo de notícias no site WordPress da escola. Na AI-School, você então insere apenas um pequeno texto, por exemplo, algumas frases sobre uma semana de projetos, dia esportivo ou dia de portas abertas. Com esse texto, você inicia o fluxo de trabalho no n8n.

O fluxo de trabalho n8n pode então, por exemplo:

1. Transformar o pequeno texto em um rascunho bem escrito com um nó LLM e um prompt que combine bem com o tom da escola.
2. Criar uma ilustração adequada com um segundo nó LLM, por exemplo, nas cores da escola e em um estilo ilustrativo reconhecível.
3. Preparar ou publicar o texto e a imagem como postagem no blog no site WordPress.

Assim, a AI-School e o n8n trabalham juntos: na AI-School, o usuário escolhe o fluxo de trabalho e preenche as informações necessárias. Depois, o n8n executa as etapas automatizadas e garante que o artigo de notícias chegue corretamente ao site.

O que faz esta integração?

Você inicia um fluxo de trabalho n8n a partir da visão geral de fluxos de trabalho. Apenas o webhook de produção, POST e Header Auth são obrigatórios. Campos e callbacks do n8n são opcionais e podem ser configurados independentemente uns dos outros.

• Se o fluxo de trabalho não tiver campos, o webhook é chamado imediatamente.
• Se o fluxo de trabalho tiver campos, primeiro abre um formulário. O usuário preenche os campos e depois inicia o fluxo de trabalho com o botão.
• Os valores preenchidos são enviados como JSON em uma requisição POST para o webhook do n8n.
• Sem callbacks, a AI-School apenas confirma que o fluxo de trabalho foi iniciado e continua no n8n. A janela não mostra spinner e pode ser fechada imediatamente.
• Se isso tiver sido ativado no registro, o fluxo de trabalho pode enviar etapas intermediárias ou o fim de volta para a AI-School.
• Se a aprovação tiver sido ativada no registro, o usuário pode fazer uma escolha diretamente na AI-School. O n8n então continua a partir da etapa de espera.

Criar fluxo de trabalho n8n na AI-School

Um administrador registra o fluxo de trabalho da seguinte forma:

1. Vá para Assistentes.
2. Abra a aba Assistentes de workflow.
3. Clique no cartão superior em Novo workflow e escolha Workflow n8n.
4. Preencha o nome do workflow e a URL de produção do n8n.
5. Configure Header authentication com um nome de cabeçalho e um valor secreto do cabeçalho.
6. Em Callbacks do n8n, marque apenas os componentes que realmente foram construídos neste workflow n8n: progresso, aprovação e/ou fim do workflow.
7. Adicione, se necessário, os campos que devem ser enviados na requisição POST.
8. Salve o workflow.

As três opções de callback ficam desativadas por padrão. Se você adicionar callbacks ou uma etapa de aprovação no n8n mais tarde, atualize também o registro na AI-School. Assim, a caixa de diálogo saberá se deve mostrar apenas uma confirmação de início ou continuar aguardando outros sinais.

Campos

• Os campos são opcionais.
• Cada campo tem um nome e um tipo.
• Os tipos de campo suportados são texto curto, texto longo, número, sim/não, data, uma opção e várias opções.
• Em Uma opção e Várias opções, adicione as opções disponíveis. Uma opção é exibida como uma lista compacta; Várias opções exibe caixas de seleção. O valor ou valores escolhidos são enviados no corpo JSON.
• Campos obrigatórios devem ser preenchidos antes que o workflow possa ser iniciado.
• O nome do campo se torna a key no corpo JSON enviado ao n8n.

Criar um workflow compatível no n8n

1. No n8n, crie um novo workflow.
2. Adicione como primeiro node um Webhook.
3. Dê a este node exatamente o nome Start workflow. Os exemplos abaixo usam esse nome.
4. Defina HTTP Method como POST.
5. Em Authentication, escolha Header Auth e selecione uma credencial Header Auth.
6. Nessa credencial, preencha o mesmo nome de cabeçalho e valor secreto usados no workflow da AI-School.
7. Defina Respond ou Response Mode como Immediately. Assim, o app recebe imediatamente uma confirmação de início bem-sucedida, enquanto o n8n continua processando.
8. Copie a Production URL do node Webhook para o campo n8n productie-url na AI-School. Não use a URL de teste com /webhook-test/.
9. Ative o workflow no n8n.

Os dados da AI-School ficam no n8n em body. Os dados de integração ficam, portanto, em body.integration. Não remova esses dados em um node Edit Fields, Set ou Code. Os exemplos abaixo sempre os leem diretamente do node Start workflow.

Exemplo do corpo JSON

Se você definir campos com os nomes prompt, klantnaam, doelgroepen e datum, o n8n recebe, por exemplo, este corpo JSON. A AI-School adiciona automaticamente o objeto integration.

{
  "prompt": "Faça um breve resumo da solicitação.",
  "klantnaam": "Organização de exemplo",
  "doelgroepen": ["funcionários", "pais"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "token-temporário-para-esta-execução"
  }
}

O token de callback pertence a uma única execução. Não o salve em logs, configuração fixa ou outros sistemas.

Opcional: enviar progresso e conclusão de volta

A AI-School pode exibir apenas o que o n8n retornar. Use esses callbacks apenas se você tiver ativado Notificar progresso intermediário e/ou Notificar o fim do workflow no registro.

Configurar o node HTTP Request

1. Adicione um node HTTP Request e nomeie-o, por exemplo, Notificar progresso.

2. Defina Method como POST.

3. Em URL, clique em Expression.

4. Cole exatamente esta expressão:

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

5. Em Authentication, escolha None. O token temporário será adicionado como cabeçalho na próxima etapa.

6. Ative Send Headers e adicione estes dois cabeçalhos:

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

7. Ative Send Body.

8. Escolha Body Content Type: JSON e Specify Body: Using JSON.

9. Cole o JSON abaixo no 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": "Criar documento"
  },
  "message": "O documento está sendo criado."
}

10. Escolha Execute step enquanto testa o workflow via o app. O node deve retornar status 200.

Copie este node HTTP Request para cada notificação de status. Em cada cópia, ajuste no mínimo eventId, step.id, step.label e message.

Configurar o callback final

Se Notificar o fim do workflow estiver ativado, deve haver um callback final no fim de cada rota possível. Use type: "completed" em caso de sucesso, type: "failed" para um erro que você trata manualmente e type: "rejected" quando o usuário rejeitar o workflow.

Para uma execução bem-sucedida, o corpo pode ser assim:

{
  "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": "Workflow concluído"
  },
  "message": "O workflow foi concluído.",
  "output": {
    "resultaat": "Breve descrição ou link para o resultado"
  }
}

Dentro de uma execução, use um eventId diferente para cada callback. Use sempre também um step.label claro: este texto é exibido ao usuário na janela de execução.

Opcional: pedir aprovação no app

Configurar o node Wait

1. No ponto em que for necessária aprovação, adicione um node Wait.
2. Em Resume, escolha On Webhook Call.
3. Defina HTTP Method como POST.
4. Em Authentication, escolha Header Auth.
5. Selecione a mesma credencial Header Auth do node Start workflow.
6. Antes do node Wait, coloque uma cópia do node HTTP Request configurado anteriormente e nomeie-a Solicitar aprovação.
7. Use neste node a mesma URL dinâmica e os mesmos cabeçalhos. Substitua apenas o corpo JSON por:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "controle-documento",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_documento",
    "label": "Verificar documento"
  },
  "approval": {
    "question": "O workflow pode continuar?",
    "context": "Primeiro verifique o documento gerado.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Aprovar" },
      { "value": "reject", "label": "Rejeitar" }
    ]
  }
}

Conecte Solicitar aprovação ao node Wait. Depois disso, o usuário verá os botões na AI-School. A resume-url secreta não é enviada ao navegador; o servidor transmite a escolha com segurança ao node Wait.

Processar a escolha após o node Wait

1. Adicione um node Switch após o node Wait.

2. Use como valor a verificar:

   {{ $json.body.decision }}

3. Crie, por exemplo, uma rota para approve e uma rota para reject.

4. Faça com que cada rota termine com um callback adequado completed, rejected ou failed.

Um valor de escolha pode conter apenas letras, números, _ e -. O rótulo pode conter texto comum e legível.

Configurar a URL de callback de produção

A URL de callback de produção para a AI-School é:

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

Não cole esta URL como texto fixo em cada node de callback. No campo URL do node HTTP Request, escolha Expression e use:

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

Assim, a AI-School fornece automaticamente a URL de produção correta a cada início. A URL fixa acima deve ser usada apenas para verificar durante os testes se a expressão aponta para a AI-School.

As callables triggerCustomN8nWorkflow, triggerN8nWorkflow e resumeN8nWorkflow são chamadas pelo próprio app. Você não precisa configurá-las no n8n.

Enviar erros inesperados

Um callback failed normal só funciona quando o workflow alcança o respectivo node HTTP Request. Para erros inesperados de nodes, use também um n8n Error Workflow central.

Criar um Error Workflow central

1. No n8n, crie um workflow separado com o nome AI-School - enviar erros.

2. Adicione um node Error Trigger.

3. Depois, adicione um node HTTP Request.

4. Defina Method como POST.

5. Em URL, insira esta URL fixa de produção:

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

6. Escolha Authentication: None.

7. Ative Send Headers e adicione:

   Name	Value
   n8n-handihow-name	o valor padrão secreto que você recebe do administrador da plataforma
   Content-Type	application/json

8. Ative Send Body, escolha JSON e cole este corpo:

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

9. Ative o Error Workflow.
10. Abra as configurações do workflow normal e, em Error Workflow, selecione este novo Error Workflow.

Sempre envie ao menos um callback de progresso imediatamente após Start workflow com executionId: "{{ $execution.id }}". Assim, o app sabe a qual execução pertence um erro inesperado do n8n.

Limitações importantes

• Apenas webhooks de gatilho são suportados.
• Apenas URLs de webhook de produção são suportadas.
• URLs de teste com /webhook-test/ são recusadas.
• Apenas POST é suportado.
• Apenas autenticação generic header é suportada.
• O valor do cabeçalho é tratado como segredo na aplicação.
• Tokens de callback e URLs de retomada são processados apenas no servidor e não ficam diretamente disponíveis para os usuários.
• O tenant é determinado no servidor com base no usuário logado, e não em um valor enviado pelo navegador.

Solução de problemas

• 404 ou webhook não registrado: ative o workflow no n8n e use a URL de produção.
• Erro de autenticação: verifique se o nome e o valor do cabeçalho são exatamente iguais em ambos os sistemas.
• Dados ausentes: verifique se os nomes dos campos na aplicação correspondem às keys que o n8n espera.
• Nenhuma requisição no n8n: verifique se o workflow começa com um gatilho de webhook e usa POST.
• A janela de execução continua carregando: você ativou Notificar o fim do workflow? Então verifique se o n8n envia um último callback completed, failed ou rejected. Se você não espera callbacks, desative as três opções no registro.
• Nenhum progresso visível: verifique se Notificar progresso intermediário está ativado no registro, se o objeto integration foi mantido e se cada callback tem um eventId único.
• Os botões de aprovação não funcionam: verifique o node Wait, resumeUrl, a autenticação por cabeçalho e os caracteres permitidos em choices[].value.