This page is not yet available in English. Read it in Portuguese

Skip to content
Menu da documentação

Autoatendimento

Automações com o seu n8n

Ligue o n8n da sua empresa a um workspace: agentes disparam workflows com aprovação humana e o n8n devolve o resultado assinado.

#Como funciona

  1. Você liga o n8n e cadastra os workflows

    Cada workflow tem uma chave, o caminho do webhook e a lista fechada de parâmetros que o agente pode mandar.

  2. O agente pede o disparo e uma pessoa aprova

    O agente usa a ferramenta automation_trigger, que sempre para e espera a aprovação humana do texto exato.

  3. A AIUBY chama o webhook

    Uma chamada POST ao seu n8n, com o segredo no cabeçalho x-aiuby-webhook-secret e um id de correlação no corpo.

  4. O workflow avisa o resultado

    No fim, o n8n chama o endereço de retorno com o mesmo id de correlação, assinado com o segredo de retorno.

A tela fica em Integrações → Automações n8n e exige o produto Agents. Quem cadastra é quem administra o workspace: dono ou administrador. Para o agente usar, libere automation_list e automation_trigger na versão dele.

#Ligar o n8n

Informe o endereço da sua instância, por exemplo https://n8n.suaempresa.com.br, e clique em Ligar n8n. Cada workspace tem um único n8n.

Regras do endereço

  • Só HTTPS, em endereço público, com até 500 caracteres.
  • Sem usuário e senha na URL, sem parâmetros de consulta e sem fragmento.
  • Endereço de rede interna é recusado: faixas privadas, loopback, link-local e metadados de nuvem. O nome é resolvido de novo a cada disparo, e a chamada é recusada se qualquer endereço resolvido for interno.
  • Redirecionamento não é seguido.

Os dois segredos

Ao ligar, a tela mostra dois segredos, uma única vez. Eles ficam cifrados na plataforma e não aparecem de novo.

SegredoPrefixoPara quê
Segredo do webhookn8nwh_Vai em cada disparo, no cabeçalho x-aiuby-webhook-secret. O seu n8n confere.
Segredo de retornon8ncb_Assina o aviso de conclusão que o seu n8n manda. A AIUBY confere.
  • Trocar o endereço mantém os segredos.
  • "Gerar segredos novos" troca os dois de uma vez, e os anteriores param na hora: atualize o n8n em seguida.
  • "Desligar n8n" remove o endereço e os workflows que nunca dispararam. Se já houve disparo, a resposta é 409: desative os workflows, e o histórico fica guardado.

#Cadastrar workflows

CampoRegra
ChaveO nome que o agente usa. Letras minúsculas, números e hífen, até 63 caracteres. Única no workspace
Caminho do webhookLetras minúsculas, números e hífen, até 100 caracteres. A chamada vai para /webhook/caminho
NomeAté 120 caracteres
O que fazAté 1.000 caracteres. O agente lê esta descrição para decidir quando usar
ParâmetrosAté 20. Nome com letras minúsculas, números e sublinhado (até 40), tipo texto, número ou sim/não, e se é obrigatório
  • Só passam os parâmetros cadastrados. Parâmetro a mais, tipo errado ou obrigatório faltando: o disparo é recusado antes da aprovação.
  • Um parâmetro de texto aceita até 2.000 caracteres.
  • O workflow nasce inativo. Crie no n8n um webhook POST nesse caminho, com autenticação por cabeçalho (nome x-aiuby-webhook-secret, valor o segredo do webhook), e só então ative.
  • Depois de criado, dá para ativar e desativar. Para mudar caminho ou parâmetros, cadastre outro workflow.
  • Excluir só funciona para workflow que nunca disparou; os demais são desativados.

#O disparo

http
POST https://n8n.suaempresa.com.br/webhook/avisar-financeiro
content-type: application/json
x-aiuby-webhook-secret: n8nwh_...

{
  "correlation_id": "3f6c2c1e-8a41-4b7e-9d53-0c1a2b3c4d5e",
  "workflow": "avisar-financeiro",
  "parameters": { "valor": 1250.5, "motivo": "Reembolso do pedido 4471" }
}

No nó Webhook do n8n, esses campos chegam em body. Guarde o correlation_id: é ele que identifica a execução no retorno.

Resposta do seu n8nO que acontece
2xx em até 15 segundosDisparo aceito. A execução fica em andamento, esperando o retorno
404Disparo recusado: workflow indisponível
Outro 3xx ou 4xxDisparo recusado
5xx, tempo esgotado ou conexão interrompidaEntrega não confirmada. Nada é repetido; uma pessoa confere
Conexão recusada ou nome não resolvidoAté 3 tentativas, com meio segundo e um segundo de espera; depois, recusado

Nota

Só há nova tentativa quando é certo que nada chegou ao n8n. Na dúvida, a plataforma não repete, para não executar duas vezes. Responda ao webhook logo e faça o trabalho demorado depois: o resultado vai pelo retorno.

O agente recebe só a situação do disparo e o id de correlação. O resultado do workflow chega depois, fora da conversa, e aparece na execução. Num fluxo, o passo de conector dispara o workflow com os parâmetros definidos no fluxo; para ter uma pessoa antes, coloque um passo de aprovação antes dele.

#O retorno

O endereço de retorno aparece na tela junto com os segredos e tem o formato https://aiuby.com/api/platform/automations/callback/{id}, em que o id identifica o n8n do workspace. A chamada não usa chave de API: quem prova a origem é a assinatura.

CabeçalhoValor
x-aiuby-timestampHora atual em segundos (Unix). Aceita até 5 minutos de diferença, para mais ou para menos
x-aiuby-signatureHMAC-SHA256 em hexadecimal, calculado com o segredo de retorno sobre o carimbo, um ponto e o corpo
CampoObrigatórioRegra
correlation_idSimO id recebido no disparo, até 100 caracteres
statusSimsucceeded ou failed
execution_idNãoId da execução no n8n, até 100 caracteres
summaryNãoResumo do que foi feito, até 2.000 caracteres

O corpo é JSON e tem até 64 KB.

Calcular a assinatura

A assinatura cobre o texto carimbo.corpo: o valor de x-aiuby-timestamp, um ponto e o corpo exatamente como é enviado. O resultado vai em hexadecimal puro, sem prefixo: é um formato diferente do aviso de conclusão de agentes, que usa v1=. Em Node.js:

javascript
import { createHmac } from 'node:crypto'

const secret = process.env.AIUBY_CALLBACK_SECRET // segredo de retorno (n8ncb_...)
const endpointId = process.env.AIUBY_ENDPOINT_ID // o fim do endereço de retorno mostrado na tela

// O corpo assinado e o corpo enviado precisam ser a mesma sequência de bytes.
const body = JSON.stringify({
  correlation_id: correlationId, // veio no corpo do disparo
  status: 'succeeded', // ou 'failed'
  execution_id: '8841', // opcional
  summary: 'Aviso enviado ao financeiro.', // opcional
})
const timestamp = String(Math.floor(Date.now() / 1000))
const signature = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')

const response = await fetch(`https://aiuby.com/api/platform/automations/callback/${endpointId}`, {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-aiuby-timestamp': timestamp,
    'x-aiuby-signature': signature,
  },
  body,
})

A tela de Automações mostra um trecho equivalente, pronto para um nó Code do n8n, já com o endereço de retorno. Para testar de fora do n8n:

bash
BODY='{"correlation_id":"'"$CORRELATION_ID"'","status":"succeeded","summary":"Aviso enviado ao financeiro."}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$AIUBY_CALLBACK_SECRET" | awk '{print $NF}')

curl -sS -X POST "https://aiuby.com/api/platform/automations/callback/$AIUBY_ENDPOINT_ID" \
  -H "content-type: application/json" \
  -H "x-aiuby-timestamp: $TS" \
  -H "x-aiuby-signature: $SIG" \
  --data-binary "$BODY"

Respostas do retorno

CódigoQuando
200Gravado ({"result":"recorded"}) ou já encerrado antes ({"result":"duplicate"})
400Corpo que não é JSON ou fora do formato
401Assinatura inválida, carimbo fora da janela ou id de endereço desconhecido
404Id de correlação que não é de um workflow deste n8n
413Corpo acima de 64 KB
429Mais de 30 assinaturas inválidas por minuto vindas do mesmo endereço IP

Sem retorno em 6 horas, a execução deixa de constar como em andamento e fica marcada como sem resposta. Um retorno que chegue depois disso ainda é aceito.

#O que fica registrado

  • Na auditoria: ligar, trocar o endereço, gerar segredos e desligar o n8n. Do endereço, só o host é gravado.
  • Na auditoria: criar, alterar e excluir workflow, com a chave, o caminho e os nomes dos parâmetros.
  • Na execução do agente ou do fluxo: cada disparo, com o id de correlação, a situação, o número de tentativas e o resumo devolvido.
  • Os segredos nunca vão para a auditoria nem para a resposta do agente.

#Limites e o que não existe

O quêLimite
n8n por workspace1
Workflows por workspace30
Disparos por execução de agente3
Alterações de cadastro30 por minuto, por pessoa
  • A AIUBY não hospeda n8n para o cliente: a instância é sua.
  • Não há disparo sem aprovação por agente, nem aprovação por chave de API.
  • O resultado do workflow não volta para a conversa do agente: fica na execução.
  • Não há repetição automática de um disparo em dúvida.
  • O cadastro é feito pela tela; não há rota por chave de API para ligar o n8n ou cadastrar workflows.
  • Não há conectores prontos para outras ferramentas de automação.