fluxos n8n

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

Exemplo: notícia no site da escola

Suponha que a escola tenha criado um fluxo n8n que publica uma notícia no site WordPress da escola. No AI-School você preenche 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 no n8n.

O fluxo n8n pode, por exemplo:

1. Transformar o texto curto em um texto conceitual utilizável com um nó LLM e um prompt que combine com o tom da escola.
2. Gerar 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 post do blog no site WordPress.

É assim que AI-School e n8n trabalham juntos: no AI-School o usuário escolhe o fluxo e preenche as informações necessárias. O n8n executa então as etapas automatizadas e garante que a notícia apareça corretamente no site.

O que faz esta integração?

Você inicia um fluxo n8n a partir da visão geral do fluxo. Apenas o webhook de produção, POST e autenticação por header são obrigatórios. Campos e retornos do n8n são opcionais e podem ser configurados independentemente.

• Se o fluxo não tiver campos, o webhook é chamado imediatamente.
• Se o fluxo tiver campos, primeiro é aberto um formulário. O usuário preenche os campos e, em seguida, inicia o fluxo com o botão.
• Os valores preenchidos são enviados como JSON no POST para o webhook do n8n.
• Sem retornos, o AI-School apenas confirma que o fluxo foi iniciado e continua no n8n. A janela não exibe um spinner e pode ser fechada imediatamente.
• Se isso estiver ativado no registro, o fluxo pode enviar de volta passos intermediários ou o fim para o AI-School.
• Se a aprovação estiver ativada no registro, o usuário pode fazer uma escolha diretamente no AI-School. Em seguida, o n8n continua a partir do passo aguardando.

Criar fluxo n8n no AI-School

Um administrador registra o fluxo da seguinte maneira:

1. Vá para Assistentes.
2. Abra Fluxos.
3. Escolha Novo fluxo n8n.
4. Informe o nome do fluxo e a URL de produção do n8n.
5. Configure Autenticação de Header com um nome de header e valor de header secreto.
6. Marque em Retornos do n8n apenas os itens que realmente foram construídos neste fluxo n8n: progresso, aprovação e/ou o fim do fluxo.
7. Adicione, se necessário, os campos que devem ser enviados no POST.
8. Salve o fluxo.

Todos os três opções de retorno aparecem desligadas por padrão. Se você mais tarde adicionar callbacks ou uma etapa de aprovação no n8n, atualize também o registro no AI-School. O diálogo saberá assim se ele deve mostrar apenas uma confirmação de início ou aguardar por sinais adicionais.

Campos

• Campos são opcionais.
• Cada campo tem um nome de campo e um tipo.
• Tipos de campo suportados: texto curto, texto longo, número, sim/não, data, uma escolha e várias escolhas.
• Em Uma escolha e Várias escolhas adicione as opções disponíveis. Uma escolha é mostrado como uma lista suspensa; Várias escolhas exibe caixas de seleção. O valor escolhido ou os valores são enviados no corpo JSON.
• Campos obrigatórios devem ser preenchidos antes que o fluxo possa ser iniciado.
• O nome do campo torna-se a chave no JSON enviado ao n8n.

Criar fluxo compatível no n8n

1. Crie um novo fluxo no n8n.
2. Adicione como primeiro nó um Webhook.
3. Difique esse nó com exatamente o nome Start workflow. Os exemplos a seguir usam esse nome.
4. Defina HTTP Method como POST.
5. Na Authentication escolha Header Auth e selecione uma credencial de Header Auth.
6. No credential, insira o mesmo nome de header e o valor secreto que foi usado para o fluxo no AI-School.
7. Defina Respond ou Response Mode como Immediately. O app recebe então uma confirmação de início bem-sucedida, enquanto o n8n continua.
8. Copie a Production URL do nó Webhook para o campo URL de produção n8n no AI-School. Não use a URL de teste com /webhook-test/.
9. Ative o fluxo no n8n.

Os dados do AI-School ficam em n8n sob body. Assim, as informações de integração ficam sob body.integration. Não remova esses dados ao editar campos, definir ou código. Os exemplos abaixo leem diretamente do nó Start workflow.

Exemplo do corpo JSON

Se você definir campos com os nomes prompt, nomeDoCliente, gruposAlvo e data, o n8n receberá, por exemplo, este corpo JSON. O AI-School adiciona automaticamente o objeto integration.

{
  "prompt": "Faça um resumo curto da solicitação.",
  "nomeDoCliente": "Organização de Exemplo",
  "gruposAlvo": ["funcionários", "pais"],
  "data": "2026-09-22",
  "integration": {
    "runId": "document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "token-temporario-para-esta-ejecucao"
  }
}

O token de callback é válido apenas para uma execução. Não o grave em logs, configurações fixas ou outros sistemas.

Opcional: retornar progresso e conclusão

AI-School pode apenas exibir o que o n8n retorna. Use esses callbacks apenas se você ativou no registro as opções de Notificar Progresso Intermediário e/ou Notificar o Fim do Fluxo.

Configurar nó HTTP Request

1. Adicione um nó HTTP Request e nomeie-o, por exemplo, Notificar Progresso.

2. Defina Method como POST.

3. Clique em URL em Expression.

4. Cole exatamente esta expressão:

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

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

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

   Nome	Valor
   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": "documento-criacao-iniciada",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "documento_criacao",
    "label": "Criação do documento"
  },
  "message": "O documento está sendo criado."
}

10. Escolha Execute step enquanto testa o fluxo na aplicação. O nó deve retornar status 200.

Copie este nó de HTTP Request para cada estado de notificação. Em cada cópia, altere ao menos eventId, step.id, step.label e message.

Configurar último callback

Se Notificar o fim do fluxo estiver ativado, deve haver um último callback no final de cada rota possível. Use type: "completed" para sucesso, type: "failed" para erro tratado por você e type: "rejected" quando o usuário rejeita o fluxo.

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": "fluxo-concluido",
  "type": "completed",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "finalizacao",
    "label": "Fluxo concluído"
  },
  "message": "O fluxo foi concluído.",
  "output": {
    "resultado": "Descrição breve ou link para o resultado"
  }
}

Use um diferente eventId para cada callback dentro da mesma execução. Sempre use um rótulo claro step.label para que o usuário veja no painel de execução.

Opcional: solicitar aprovação no app

Configurar nó Wait

1. Adicione um nó Wait no local onde a aprovação é necessária.
2. Escolha em Resume a opção On Webhook Call.
3. Defina HTTP Method como POST.
4. Em Authentication escolha Header Auth.
5. Selecione a mesma credencial de Header Auth usada no nó Start workflow.
6. Coloque antes do nó Wait uma cópia do nó HTTP Request configurado anteriormente e nomeie-o como Solicitar aprovação.
7. Use neste nó 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-de-documento",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_documento",
    "label": "Verificar documento"
  },
  "approval": {
    "question": "O fluxo pode continuar?",
    "context": "Verifique primeiro o documento gerado.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Aprovar" },
      { "value": "reject", "label": "Rejeitar" }
    ]
  }
}

Conecte o Solicitar aprovação ao nó Wait. O usuário verá os botões no AI-School. A URL de resume secreta não é exibida no navegador; o servidor envia a escolha com segurança ao nó Wait.

Processar a escolha após o Wait

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

2. Use como valor a verificar:

   {{ $json.body.decision }}

3. Crie, por exemplo, rotas para approve e reject.

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

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

Configurar a URL de callback de produção

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

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

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

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

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

As chamadas triggerCustomN8nWorkflow, triggerN8nWorkflow e resumeN8nWorkflow são chamadas pela própria aplicação. Não é necessário configurar essas URLs no n8n.

Enviar erros inesperados

Um callback failed simples funciona apenas quando o nó HTTP Request relevante é alcançado pela workflow. Use também um fluxo de erro central no n8n para erros de nó inesperados.

Criar Fluxo de Erro Central

1. No n8n, crie um fluxo separado chamado AI-School - envio de erros.

2. Adicione um nó Error Trigger.

3. Em seguida, adicione um nó HTTP Request.

4. Defina Method como POST.

5. Insira na URL esta URL de produção fixa:

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

6. Escolha Authentication: None.

7. Ative Send Headers e adicione:

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

8. Ative Send Body, escolha JSON e cole o 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 Fluxo de Erro.
10. Abra as configurações do fluxo comum e selecione, em Erro do Fluxo, esse novo Fluxo de Erro.

Depois de Start workflow, envie sempre pelo menos um callback de progresso com executionId: "{{ $execution.id }}". Assim, o app sabe em qual execução ocorreu o erro n8n inesperado.

Limitações importantes

• Apenas gatilhos de webhook são suportados.
• Apenas URLs de webhook de produção são suportadas.
• URLs de webhook de teste com /webhook-test/ são rejeitadas.
• Apenas POST é suportado.
• Apenas autenticação genérica por header é suportada.
• O valor do header é tratado como segredo pela aplicação.
• Tokens de callback e URLs de resume são processados apenas no servidor e não estão disponíveis diretamente para usuários.
• O tenant é determinado no servidor a partir do usuário conectado, não a partir de um valor enviado pelo navegador.

Solução de problemas

• 404 ou webhook não registrado: ative o fluxo no n8n e use a URL de produção.
• Erro de autenticação: verifique se o nome do header e o valor são exatamente iguais nos dois sistemas.
• Dados ausentes: verifique se os nomes dos campos no aplicativo correspondem às chaves esperadas pelo n8n.
• Sem requisição no n8n: verifique se o fluxo começa com um gatilho de webhook e usa POST.
• A janela de execução fica girando: se você ativou Notificar o fim do fluxo, verifique se o n8n enviou um último callback completed, failed ou rejected. Se você não espera por retornos, desative as três opções no registro.
• Nenhuma progressão visível: verifique se Notificar Progresso Intermediário está ativo no registro, ou se o objeto integration é mantido e se cada callback tem um eventId único.
• Botões de aprovação não funcionam: verifique o nó Wait, resumeUrl, autenticação por header e os caracteres permitidos em choices[].value.