workflows n8n

O AI-Public pode iniciar workflows n8n por meio de um webhook de produção. Isso é útil quando você quer iniciar um processo automatizado fora do AI-Public, 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 organização

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

O workflow n8n pode então, por exemplo:

1. Transformar o texto curto em um rascunho bem escrito com um nó LLM e um prompt que se encaixe bem no tom da organização.
2. Gerar uma ilustração adequada com um segundo nó LLM, por exemplo nas cores da identidade visual e em um estilo ilustrativo reconhecível.
3. Preparar ou publicar o texto e a imagem como post de blog no site WordPress.

Assim, o AI-Public e o n8n trabalham juntos: no AI-Public, 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 callbacks do n8n são opcionais e podem ser configurados de forma independente.

• Se o workflow não tiver campos, o webhook é chamado imediatamente.
• Se o workflow tiver campos, primeiro abre-se um formulário. 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 requisição POST para o webhook do n8n.
• Sem callbacks, o AI-Public 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 término para o AI-Public.
• Se a aprovação tiver sido ativada no registro, o usuário pode fazer uma escolha diretamente no AI-Public. O n8n então continua a partir da etapa de espera.

Criar um workflow n8n no AI-Public

Um administrador registra o workflow da seguinte forma:

1. Vá para Assistentes.
2. Abra a aba Assistentes de workflow.
3. Na carta no topo, clique 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 header e um valor secreto de header.
6. Em Callbacks do n8n, marque apenas os componentes que realmente foram construídos neste workflow n8n: progresso, aprovação e/ou o 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 no AI-Public. Assim, a janela 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 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 é exibida como uma lista suspensa compacta; Múltiplas escolhas exibe caixas de seleção. O valor ou os 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 chave no corpo JSON enviado ao n8n.

Criar um workflow compatível no n8n

1. Crie um novo workflow no n8n.
2. Adicione como primeiro node um Webhook.
3. Dê a esse node exatamente o nome Start workflow. As expressões de exemplo abaixo usam esse nome.
4. Defina HTTP Method como POST.
5. Escolha Authentication: Header Auth e use o mesmo nome de header e valor secreto que no AI-Public.
6. Defina Respond ou Response Mode como Immediately.
7. Copie a Production URL para o campo n8n productie-url no AI-Public. Não use a test-url com /webhook-test/.
8. Ative o workflow.

Os dados recebidos ficam em body; os dados técnicos da 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-Public adiciona automaticamente o objeto integration.

{
  "prompt": "Maak een korte samenvatting van de aanvraag.",
  "klantnaam": "Voorbeeldorganisatie",
  "doelgroepen": ["inwoners", "medewerkers"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-public-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "tijdelijk-token-voor-deze-uitvoering"
  }
}

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

Opcional: enviar progresso e conclusão

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

Configure cada node de callback da seguinte forma:

1. Escolha Method: POST.

2. Clique em URL e selecione Expression, depois cole:

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

3. Escolha Authentication: None.

4. Ative Send Headers e adicione os headers abaixo.

5. 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": "Document maken"
  },
  "message": "Het document wordt gemaakt."
}

• Use um eventId único para cada evento dentro da mesma execução.
• Use um step.label claro em holandês; esse texto é exibido no app.
• Se você ativou Reportar o fim do workflow, envie sempre no final type: "completed", type: "failed" ou type: "rejected".
• Em completed, você pode adicionar um objeto output com o resultado.
• Em failed, envie também uma mensagem de erro compreensível. A execução entã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. Antes do node Wait, envie um callback com type: "approval_required":

Configure o node Wait com Resume: On Webhook Call, HTTP Method: POST e Authentication: Header Auth. Selecione a mesma credencial Header Auth usada em Start workflow. Depois do node Wait, adicione um node 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": "Mag de workflow doorgaan?",
    "context": "Controleer eerst het gegenereerde document.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Goedkeuren" },
      { "value": "reject", "label": "Afwijzen" }
    ]
  }
}

O usuário verá as escolhas na janela de execução. Após uma escolha, o node Wait recebe, entre outros, decision. Depois disso, 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-Public é:

https://europe-west1-ai-public-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, o AI-Public 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-Public e não para o AI-School ou AI-Corporate.

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

Tratar erros

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

1. Crie um novo workflow com um node Error Trigger.

2. Depois, adicione um node HTTP Request com Method: POST.

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

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

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

5. 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 }}"
}

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

Logo após Start workflow, envie pelo menos um callback com executionId: "{{ $execution.id }}". Só assim o AI-Public 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 segredo na aplicação.
• Tokens de callback e URLs de retomada são processados apenas no lado do servidor e não ficam diretamente disponíveis para usuários.
• O tenant é determinado no lado do servidor com base no usuário autenticado, não a partir 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 nos dois sistemas.
• Dados ausentes: verifique se os nomes dos campos na aplicação correspondem às chaves que o n8n espera.
• Nenhuma requisição no n8n: verifique se o workflow começa com um trigger de webhook e usa POST.
• A janela de execução continua carregando: se você ativou Reportar o fim do workflow, verifique se o n8n envia um último callback completed, failed ou rejected. Se você não espera callbacks, desative todas as três opções no registro.
• Nenhum progresso visível: verifique se Reportar 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.