fluxos de n8n

AI-Corporate pode iniciar fluxos n8n via um webhook de produção. Isso é útil quando você quer iniciar um processo automatizado fora do AI-Corporate, 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: artigo de notícias no site da empresa

Suponha que a organização tenha criado um fluxo n8n que publique um artigo de notícias no site WordPress da empresa. No AI-Corporate você insere apenas um breve texto, por exemplo alguns parágrafos sobre um caso de cliente, evento ou marco interno. Com esse texto você inicia o fluxo no n8n.

O fluxo do n8n pode, em seguida, por exemplo:

Transformar o texto curto em um rascunho com uma node LLM e um prompt que combine com o tom da organização.
Criar uma ilustração adequada com um segundo node LLM, por exemplo nas cores da marca 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-Corporate e n8n trabalham juntos: no AI-Corporate o usuário seleciona o fluxo de trabalho e preenche as informações necessárias. O n8n executa então as etapas automatizadas e garante que a notícia apareça de forma adequada no site.

O que faz esta integração?

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

Se o fluxo de trabalho não tiver campos, o webhook é acionado imediatamente.
Se o fluxo tiver campos, abre-se primeiro 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-Corporate apenas confirma que o fluxo foi iniciado e continua no n8n. A janela não mostra spinner e pode ser fechada imediatamente.
Se isso estiver ativado na configuração, o fluxo pode enviar de volta etapas intermediárias ou o final para o AI-Corporate.
Se a aprovação estiver ativada na configuração, o usuário pode fazer a escolha diretamente no AI-Corporate. O n8n continua então a partir da etapa aguardando.

Criar fluxo de n8n no AI-Corporate

Um administrador registra o fluxo de trabalho da seguinte maneira:

Vá para Assistentes.
Abra Fluxos de Trabalho.
Escolha Novo fluxo de n8n.
Preencha o nome do fluxo de trabalho e a URL de produção do n8n.
Configure Autenticação de cabeçalho com um nome de cabeçalho e valor de cabeçalho secreto.
Marque em Feedbacks de n8n apenas os itens que realmente foram construídos neste fluxo de n8n: progresso, aprovação e/ou o fim do fluxo.
Adicione, se necessário, os campos que devem ser enviados no POST.
Salve o fluxo de trabalho.

Todos os três opt-outs de feedback permanecem desativados por padrão. Se você adicionar callbacks ou uma etapa de aprovação no n8n depois, atualize também o registro no AI-Corporate. A caixa de diálogo saberá então se deve mostrar apenas uma confirmação de início ou esperar por sinais adicionais.

Campos

Campos são opcionais.
Cada campo tem um único nome de campo e um tipo.
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 de opções compacta; Várias opções mostra 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 corpo JSON enviado ao n8n.

Criar fluxo de trabalho compatível no n8n

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

Os dados recebidos ficam sob body; os dados de integração técnica ficam em body.integration. Não remova isso em uma node de Edit Fields, Set ou Code.

Exemplo do corpo JSON

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

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

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

Opcional: enviar progresso e conclusão

AI-Corporate pode apenas mostrar o que o n8n retornar. Use esses callbacks apenas se, na configuração, você habilitou Notificar progresso intermediário e/ou Notificar o fim do fluxo.

Configure cada node 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 seguintes headers.
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-maken-gestart",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "Document maken"
  },
  "message": "O documento está sendo criado."
}

Use um eventId único para cada evento dentro da mesma execução.
Use um rótulo de passo claro em holandês; esse texto será exibido no app.
Se você ativou Notificar o fim do fluxo, envie sempre no fim type: "completed", type: "failed" ou type: "rejected".
Em completed, opcionalmente inclua um objeto output com o resultado.
Em failed envie uma mensagem de erro compreensível. A execução também deverá parar no app.

Opcional: solicitar aprovação no app

Use um nó n8n Wait com On Webhook Call quando o fluxo só puder 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 a mesma credencial de Header Auth que em Start workflow. Adicione depois do 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": "Document controleren"
  },
  "approval": {
    "question": "A workflow pode continuar?",
    "context": "Primeiro verifique o documento gerado.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Aprovar" },
      { "value": "reject", "label": "Rejeitar" }
    ]
  }
}

O usuário verá as opções na janela de execução. Após uma escolha, a node Wait receberá entre outras coisas decision. Em seguida, use, por exemplo, um nó Switch para determinar o seguimento correto.

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

Configurar a URL de callback de produção

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

https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowCallback

Não insira esta URL como texto fixo em cada node de callback. Escolha no campo de URL do nó de HTTP Request a opção Expression e use:

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

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

As chamadas triggerCustomN8nWorkflow, triggerN8nWorkflow e resumeN8nWorkflow são chamadas pela própria aplicação. Você não precisa configurá-las no n8n.

Tratamento de erros

Envie erros esperados com um callback do tipo failed. Para erros de nó inesperados, crie também um fluxo de Erro central:

Crie um novo fluxo com um nó Error Trigger.
Em seguida adicione um nó HTTP Request com Method: POST.

Preencha a URL com esta URL de produção fixa:

https://europe-west1-ai-corporate.cloudfunctions.net/n8nWorkflowExecutionFailed

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

{
  "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 de trabalho comum e selecione este fluxo em Error Workflow.

Envie imediatamente após o Start workflow pelo menos um callback com executionId: "{{ $execution.id }}". Somente assim o AI-Corporate consegue vincular uma falha inesperada à execução correta.

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 de cabeçalho genérica é suportada.
O valor do cabeçalho é 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 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 do cabeçalho e o valor são exatamente iguais em ambos os sistemas.
Dados ausentes: verifique se os nomes dos campos na aplicação correspondem às chaves esperadas pelo n8n.
Sem requisição no n8n: verifique se o fluxo começa com um webhook trigger e usa POST.
A janela de execução permanece girando: se você ativou Notificar o fim do fluxo, verifique se o n8n envia um callback final completed, failed ou rejected. Se você não espera feedbacks, desative as três opções na configuração.
Progresso não visível: verifique se Notificar progresso intermediário está ativado na configuração, ou se o objeto integration é mantido e se cada callback possui um eventId único.
Botões de aprovação não funcionam: verifique o node Wait, resumeUrl, autenticação de cabeçalho e os caracteres permitidos em choices[].value.

Exemplo: artigo de notícias no site da empresa​

O que faz esta integração?​

Criar fluxo de n8n no AI-Corporate​

Campos​

Criar fluxo de trabalho compatível no n8n​

Exemplo do corpo JSON​

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​