fluxos n8n

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

Exemplo: artigo de notícias no site da organização

Suponha que a organização tenha criado um fluxo n8n que publica uma notícia no site WordPress. No AI-Public você preenche apenas um breve texto, por exemplo algumas frases sobre uma reunião, projeto ou anúncio público. Com esse texto você inicia o fluxo no n8n.

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

A partir do texto curto, criar um rascunho adequado com um nó LLM e um prompt que combine com o tom da organização.
Gerar uma ilustração apropriada com um segundo nó LLM, por exemplo nas cores da identidade visual e em um estilo ilustrativo reconhecível.
Preparar ou publicar o texto e a imagem como uma postagem de blog no site WordPress.

É assim que AI-Public e n8n trabalham juntos: no AI-Public o usuário escolhe o fluxo de trabalho e fornece as informações necessárias. O n8n executa as etapas automatizadas e garante que a notícia apareça na página.

O que faz essa integração?

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

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

Criar fluxo n8n no AI-Public

Um gerente registra o fluxo da seguinte forma:

Vá para Assistentes.
Abra Fluxos de Trabalho.
Selecione Novo fluxo n8n.
Preencha o nome do fluxo e a URL de produção do n8n.
Configure Autenticação de Header com um nome de header e valor secreto.
Marque em Feedbacks de n8n apenas as partes que realmente foram construídas neste fluxo n8n: progresso, aprovação e/ou o fim do fluxo.
Adicione, se desejar, os campos que devem ser enviados no POST.
Salve o fluxo.

Todas as três opções de feedback vêm desativadas por padrão. Se mais tarde você adicionar callbacks ou uma etapa de aprovação no n8n, atualize também o registro no AI-Public. O diálogo saberá então se ele deve mostrar apenas uma confirmação de início ou continuar aguardando por sinais adicionais.

Campos

Campos são opcionais.
Cada campo tem um nome de campo e um tipo.
Os tipos de campo suportados são texto curto, texto longo, número, sim/não, data, uma escolha e várias escolhas.
Em Uma escolha e Várias escolhas você adiciona as opções disponíveis. Uma escolha é exibida como uma lista de opções compacta; Várias escolhas mostra caixas de seleção. O valor ou valores escolhidos 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 corpo JSON enviado ao n8n.

Criar fluxo compatível no n8n

Crie no n8n um novo fluxo.
Adicione como primeiro nó um Webhook.
Dê exatamente o nome Start workflow a este nó. As expressões de exemplo abaixo usam esse nome.
Defina HTTP Method como POST.
Escolha Authentication: Header Auth e use o mesmo nome de header e valor secreto que no AI-Public.
Defina Respond ou Response Mode como Immediately.
Copie a Production URL para o campo n8n produção-url no AI-Public. Não use a URL de teste com /webhook-test/.
Ative o fluxo.

Os dados recebidos ficam em body; os dados de integração ficam em body.integration. Não apague isso em um nó Edit Fields-, Set- ou Code.

Exemplo do JSON body

Se você definir campos com os nomes prompt, cliente, público-alvo e data, o n8n receberá, por exemplo, este body JSON. O AI-Public adiciona automaticamente o objeto integration.

{
  "prompt": "Faça um resumo curto da solicitação.",
  "cliente": "Organização de Exemplo",
  "público-alvo": ["moradores", "funcionários"],
  "data": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-public-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "token-temporario-para-esta-execução"
  }
}

O token de callback pertence a uma única execução. Não o registre em logs, configurações fixas ou outros sistemas.

Opcional: enviar progresso e conclusão

AI-Public pode apenas mostrar o que o n8n retorna. Use esses callbacks apenas se, no registro, você tiver ativado Reportar Progresso Intermediário e/ou Relatar o fim do fluxo.

Configure cada nó de callback da seguinte forma:

Escolha Method: POST.

Clique em URL em Expression e cole:

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

Escolha Authentication: None.
Ative Send Headers e adicione os headers abaixo.
Ative Send Body e escolha Body Content Type: JSON e Specify Body: Using JSON.

Use estes headers:

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

Envie, por exemplo, esta mensagem quando uma etapa começar:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-criar-iniciado",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_criar",
    "label": "Criar Documento"
  },
  "message": "O documento está sendo criado."
}

Use para cada evento dentro da mesma execução um eventId único.
Use um step.label claro em holandês; esse texto é exibido no app.
Se você ativou Relatar o fim do fluxo, envie no final sempre type: "completed", type: "failed" ou type: "rejected".
Ao completed, se desejar, adicione um objeto output com o resultado.
Em caso de failed, inclua uma mensagem de erro compreensível. A execução também para no app.

Opcional: solicitar aprovação no app

Use um nó n8n Wait com On Webhook Call quando o fluxo só pode continuar após uma escolha. Envie antes do Wait um callback com type: "approval_required":

Configure o nó Wait para Resume: On Webhook Call, HTTP Method: POST e Authentication: Header Auth. Selecione as mesmas credenciais de Header Auth que em Start workflow. Adicione após o Wait um nó Switch e verifique {{ $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": "Documento verificar"
  },
  "approval": {
    "question": "O fluxo pode continuar?",
    "context": "Verifique primeiro o documento gerado.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Aprovar" },
      { "value": "reject", "label": "Rejeitar" }
    ]
  }
}

O usuário vê as escolhas na janela de execução. Após uma escolha, a Wait node terá, entre outros, decision. Em seguida use, por exemplo, um nó Switch para determinar o próximo passo.

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

Configurar a URL de callback de produção

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

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

Não cole essa URL como texto fixo em todas as nodes de callback. Escolha em Expression no campo URL da HTTP Request node e use:

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

O AI-Public fornece automaticamente a URL de produção correta a cada início. A URL fixa acima é usada apenas para testar se a expressão aponta para o AI-Public e não para o AI-School ou AI-Corporate.

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

Tratamento de erros

Envie erros esperados com um callback do tipo failed. Crie também um Fluxo de Erro Central para erros inesperados:

Crie um novo fluxo com um nó Error Trigger.
Adicione depois um nó HTTP Request com Method: POST.

No URL coloque esta URL de produção fixa:

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

Escolha Authentication: None e adicione o header n8n-handihow-name com o valor secreto padrão do administrador da plataforma.
Escolha um corpo JSON e insira:

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

Ative o Fluxo de Erro.
Abra as configurações do fluxo normal e selecione-o em Erro de Fluxo.

Envie assim que houver Start workflow pelo menos um callback com executionId: "{{ $execution.id }}". Somente assim o AI-Public pode associar um erro inesperado à execução correta.

Limitações importantes

Apenas gatilhos webhook são suportados.
Apenas URLs de webhook de produção são suportadas.
Webhook de teste com /webhook-test/ são rejeitados.
Apenas POST é suportado.
Apenas autenticação de header genérica é suportada.
O value do header é tratado como segredo na aplicação.
Tokens de callback e URLs de resume são processados apenas no servidor e não estão disponíveis diretamente para os usuários.
O tenant é determinado no servidor a partir do usuário que está logado, 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 de header e o valor são idênticos em ambos os sistemas.
Dados ausentes: verifique se os nomes de campo na aplicação correspondem às keys que o n8n espera.
Sem request no n8n: verifique se o fluxo começa com um webhook trigger e usa POST.
A janela de execução permanece funcionando: se você ativou o fim do fluxo, verifique se o n8n envia um callback final completed, failed ou rejected. Se não esperar feedbacks, desative as três opções no registro.
Progresso não visível: verifique se Reportar 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 node Wait, o resumeUrl, a autenticação de header e os caracteres permitidos em choices[].value.

Exemplo: artigo de notícias no site da organização​

O que faz essa integração?​

Criar fluxo n8n no AI-Public​

Campos​

Criar fluxo compatível no n8n​

Exemplo do JSON body​

Opcional: enviar progresso e conclusão​

Opcional: solicitar aprovação no app​

Configurar a URL de callback de produção​

Tratamento de erros​

Limitações importantes​

Solução de problemas​