workflows n8n

AI-Corporate pode iniciar workflows n8n por meio de 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órios 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 workflow n8n que publica um artigo de notícias no site WordPress da empresa. No AI-Corporate, você preenche apenas um pequeno trecho de texto, por exemplo, algumas frases sobre um caso de cliente, evento ou marco interno. Com esse texto, você inicia o workflow no n8n.

O workflow n8n pode então, por exemplo:

Transformar o texto curto em um rascunho bem escrito com um node LLM e um prompt que combine bem 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 postagem de blog no site WordPress.

Assim, AI-Corporate e n8n trabalham juntos: no AI-Corporate, o usuário escolhe o workflow e preenche as informações necessárias. Em seguida, o n8n executa as etapas automatizadas e garante que o artigo de notícias chegue corretamente ao site.

O que esta integração faz?

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

Se o workflow não tiver campos, o webhook é chamado imediatamente.
Se o workflow tiver campos, primeiro um formulário é aberto. O usuário preenche os campos e depois inicia o workflow com o botão.
Os valores preenchidos são enviados como JSON em uma solicitação POST para o webhook do n8n.
Sem retornos, o AI-Corporate apenas confirma que o workflow 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 workflow pode enviar etapas intermediárias ou o fim de volta ao AI-Corporate.
Se a aprovação tiver sido ativada no registro, o usuário pode fazer uma escolha diretamente no AI-Corporate. O n8n então continua a partir da etapa de espera.

Criar workflow n8n no AI-Corporate

Um administrador registra o workflow da seguinte forma:

Vá para Assistentes.
Abra a aba Assistentes de workflow.
Clique em Novo workflow no cartão no topo e escolha Workflow n8n.
Preencha o nome do workflow e a URL de produção do n8n.
Configure Header authentication com um nome de header e um valor secreto de header.
Em Retornos do n8n, marque apenas os componentes que realmente foram construídos neste workflow n8n: progresso, aprovação e/ou o fim do workflow.
Adicione, se necessário, os campos que devem ser enviados na solicitação POST.
Salve o workflow.

As três opções de retorno estão 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-Corporate. Assim, o diálogo sabe se deve mostrar apenas uma confirmação de início ou se deve continuar aguardando sinais adicionais.

Campos

Os 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 múltiplas escolhas.
Em Uma escolha e Múltiplas escolhas, adicione as opções disponíveis. Uma escolha é mostrada como uma lista de seleção compacta; Múltiplas escolhas mostra caixas de seleção. O valor ou valores escolhidos são enviados no corpo JSON.
Os campos obrigatórios devem ser preenchidos antes que o workflow possa ser iniciado.
O nome do campo se torna a chave no corpo JSON enviado ao n8n.

Criar um workflow compatível no n8n

Crie um novo workflow no n8n.
Adicione um node Webhook como primeiro node.
Dê a este node exatamente o nome 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 header e valor secreto do 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 workflow.

Os dados recebidos ficam em body; os dados técnicos de integração ficam em body.integration. Não os remova em um node 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 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

O AI-Corporate só pode mostrar o que o n8n retornar. Use esses callbacks apenas se, no registro, você tiver ativado Relatar progresso intermediário e/ou Relatar o fim do workflow.

Configure cada node de callback da seguinte forma:

Escolha Method: POST.

Clique em Expression em URL 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

Por exemplo, envie 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": "Criar documento"
  },
  "message": "O documento está sendo criado."
}

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

Opcional: solicitar aprovação no app

Use um node Wait do n8n com On Webhook Call quando o workflow só puder continuar após uma escolha. Envie, antes do node Wait, um callback com type: "approval_required":

Configure o node Wait em Resume: On Webhook Call, HTTP Method: POST e Authentication: Header Auth. Selecione a mesma credencial Header Auth usada em Start workflow. Adicione um node Switch após o node Wait e verifique {{ $json.body.decision }}.

{
  "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" }
    ]
  }
}

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

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

Definir a URL de callback de produção

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

https://europe-west1-ai-corporate.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, o AI-Corporate fornece automaticamente a URL de produção correta a cada início. A URL fixa acima é usada para verificar, durante os testes, se a expressão aponta para o AI-Corporate e não para o AI-School ou o AI-Public.

As callables triggerCustomN8nWorkflow, triggerN8nWorkflow e resumeN8nWorkflow são chamadas pelo próprio app. Você não precisa definir essas URLs no n8n.

Tratar erros

Retorne erros esperados com um callback do tipo failed. Para erros inesperados de nodes, crie também um Error Workflow central:

Crie um novo workflow com um node Error Trigger.
Em seguida, adicione um node HTTP Request com Method: POST.

Em URL, preencha esta URL fixa de produção:

https://europe-west1-ai-corporate.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 cole:

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

Ative o Error Workflow.
Abra as configurações do workflow normal e selecione-o em Error Workflow.

Envie logo após Start workflow pelo menos um callback com executionId: "{{ $execution.id }}". Só assim o AI-Corporate pode associar um erro inesperado à execução correta.

Limitações importantes

Apenas triggers de webhook 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 genérica por header é suportada.
O valor do header é tratado como secreto no aplicativo.
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 a partir do usuário autenticado, não de 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 header são exatamente iguais em ambos os sistemas.
Dados ausentes: verifique se os nomes dos campos no aplicativo correspondem às chaves esperadas pelo n8n.
Nenhuma solicitação no n8n: verifique se o workflow começa com um webhook trigger e usa POST.
A janela de execução continua rodando: se você ativou Relatar o fim do workflow, verifique se o n8n envia um callback final completed, failed ou rejected. Se não esperar retornos, desative as três opções no registro.
Nenhum progresso visível: verifique se Relatar progresso intermediário está ativado no registro, se o objeto integration foi preservado 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 header e os caracteres permitidos em choices[].value.

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

O que esta integração faz?​

Criar workflow n8n no AI-Corporate​

Campos​

Criar um workflow compatível no n8n​

Exemplo do corpo JSON​

Opcional: enviar progresso e conclusão de volta​

Opcional: solicitar aprovação no app​

Definir a URL de callback de produção​

Tratar erros​

Limitações importantes​

Solução de problemas​