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
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.
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.A AIUBY chama o webhook
Uma chamada
POSTao seu n8n, com o segredo no cabeçalhox-aiuby-webhook-secrete um id de correlação no corpo.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.
| Segredo | Prefixo | Para quê |
|---|---|---|
| Segredo do webhook | n8nwh_ | Vai em cada disparo, no cabeçalho x-aiuby-webhook-secret. O seu n8n confere. |
| Segredo de retorno | n8ncb_ | 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
| Campo | Regra |
|---|---|
| Chave | O nome que o agente usa. Letras minúsculas, números e hífen, até 63 caracteres. Única no workspace |
| Caminho do webhook | Letras minúsculas, números e hífen, até 100 caracteres. A chamada vai para /webhook/caminho |
| Nome | Até 120 caracteres |
| O que faz | Até 1.000 caracteres. O agente lê esta descrição para decidir quando usar |
| Parâmetros | Até 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
POSTnesse caminho, com autenticação por cabeçalho (nomex-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
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 n8n | O que acontece |
|---|---|
| 2xx em até 15 segundos | Disparo aceito. A execução fica em andamento, esperando o retorno |
| 404 | Disparo recusado: workflow indisponível |
| Outro 3xx ou 4xx | Disparo recusado |
| 5xx, tempo esgotado ou conexão interrompida | Entrega não confirmada. Nada é repetido; uma pessoa confere |
| Conexão recusada ou nome não resolvido | Até 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çalho | Valor |
|---|---|
x-aiuby-timestamp | Hora atual em segundos (Unix). Aceita até 5 minutos de diferença, para mais ou para menos |
x-aiuby-signature | HMAC-SHA256 em hexadecimal, calculado com o segredo de retorno sobre o carimbo, um ponto e o corpo |
| Campo | Obrigatório | Regra |
|---|---|---|
correlation_id | Sim | O id recebido no disparo, até 100 caracteres |
status | Sim | succeeded ou failed |
execution_id | Não | Id da execução no n8n, até 100 caracteres |
summary | Não | Resumo 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:
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:
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ódigo | Quando |
|---|---|
200 | Gravado ({"result":"recorded"}) ou já encerrado antes ({"result":"duplicate"}) |
400 | Corpo que não é JSON ou fora do formato |
401 | Assinatura inválida, carimbo fora da janela ou id de endereço desconhecido |
404 | Id de correlação que não é de um workflow deste n8n |
413 | Corpo acima de 64 KB |
429 | Mais 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 workspace | 1 |
| Workflows por workspace | 30 |
| Disparos por execução de agente | 3 |
| Alterações de cadastro | 30 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.