Ferramentas HTTP com Make, n8n e Zapier
Se o teu software não tem API, ou só tem OAuth2, podes pôr um destes serviços pelo meio. A ferramenta HTTP chama um webhook do serviço, o serviço fala com o teu software e responde ao agente. Esta página explica o que cada um devolve e o que a Atendia faz com isso.
Make: testado numa chamada real a 2026-11-02, com uma ferramenta HTTP. n8n: testado numa chamada real a 2026-11-02, com uma ferramenta HTTP e o webhook de fim de chamada, sem assinatura; o código de verificação foi testado fora do n8n. Zapier: segundo a documentação de 2026-10-30. Não o testámos.
Os modelos da Atendia
- Quando o Construtor prepara uma ferramenta de consulta ou o webhook pós-chamada para o Make ou para o n8n, o cartão traz um modelo pronto. O cartão reconhece o Make pelo cabeçalho
x-make-apikeyou por um endereçohook.….make.com, e o n8n pelo cabeçalhox-n8n-keyou por um endereço….n8n.cloud. - Make: carrega em «Abrir modelo no Make». O cenário abre noutro separador e já traz a resposta certa para o agente.
- n8n: carrega em «Copiar fluxo para o n8n». No n8n, abre um fluxo novo e cola (Ctrl+V; no Mac, Cmd+V). Se abrir uma janela, carrega em «Skip». Depois segue a nota «Como usar» do fluxo.
- A chave do n8n: carrega em «Copiar chave para o n8n». A consola cria uma chave, põe-na no cartão, no cabeçalho
x-n8n-key, e copia-a. No n8n, no nó «Webhook», cria a credencial com «Name»x-n8n-keye cola a chave em «Value». Também podes escrever a tua. - No n8n, carrega em «Publish» e, na janela, outra vez em «Publish». Depois copia o «Production URL» e cola-o no cartão, em «Endereço de destino».
- No webhook pós-chamada, antes de carregares em «Enviar exemplo e ativar»: no Make, o webhook tem de mostrar «Listening for data»; no n8n, o fluxo tem de estar publicado. Sem isso, o exemplo não chega.
Tempo limite
- O agente fica à espera da resposta durante a conversa. Pessoas ao telefone não esperam muito: põe o tempo limite da ferramenta em poucos segundos (por exemplo, 10), no máximo.
- O tempo limite da ferramenta tem de ficar abaixo do da plataforma. Se a plataforma demorar mais do que a ferramenta, a Atendia desiste primeiro e o agente diz que a confirmação está pendente.
- Faz o trabalho lento depois de responder, ou noutro fluxo. Responde ao agente só com o que ele precisa.
- Uma ferramenta que escreve (POST, PUT, PATCH, DELETE) e fica sem resposta dentro do tempo deixa o resultado por confirmar. O agente não repete sozinho.
Make
- Cria um cenário que começa com «Custom webhook» e copia o endereço para a ferramenta. Em «Advanced settings», liga «Get request headers» se queres ler os cabeçalhos.
- Acaba o cenário com o módulo «Webhook Response». Defines o estado (200), o corpo e o cabeçalho
Content-Type: application/json. O que puseres no corpo é o que o agente recebe. - O Make espera até 180 segundos pela resposta. Passado esse tempo, devolve
200 Acceptedsem os teus dados. Por isso o tempo limite da ferramenta tem de ficar muito abaixo disso. - Se o cenário falhar, devolve um estado de erro (por exemplo 500) no «Webhook Response». A Atendia traduz o código numa frase fixa para o agente.
- O Make só devolve os dados com o cenário ligado e em «Immediately as data arrives». Desligado, ou agendado a intervalos (por exemplo «Every 15 minutes»), responde logo
200com o texto «Accepted», põe o pedido em fila e não corre o cenário. Um cenário desligado não deixa histórico: sem execuções para ver, liga-o primeiro. Escolhe os campos da resposta na ferramenta, para esse «Accepted» contar como falha, também no teste da ferramenta. 410: o endereço do webhook já não tem cenário (passaram mais de 5 dias sem cenário). Cria o cenário outra vez e escreve o endereço novo na ferramenta.400«Queue is full.»: a fila do webhook está cheia porque o cenário não despacha os pedidos. Liga o cenário em «Immediately» ou espera que a fila esvazie.429: pedidos a mais; espera e tenta de novo.
n8n
- Cria um fluxo com o nó «Webhook», método igual ao da ferramenta, e copia o endereço de produção para a ferramenta. Publica o fluxo («Publish»): sem isso, a ferramenta recebe um erro 404.
- No nó «Webhook», põe «Respond» em «Using 'Respond to Webhook' Node». Acaba o fluxo com o nó «Respond to Webhook», com «Respond With» em «JSON» ou «First Incoming Item». O que responder é o que o agente recebe.
- Para verificar a assinatura, liga a opção «Raw Body» do nó «Webhook» (o corpo exato) e põe a seguir um nó de código com o exemplo abaixo. Confirma no painel de saída onde o n8n guarda o corpo: o exemplo lê-o do campo binário
data. - O nó de código precisa de
crypto: o n8n só o deixa usar se a variávelNODE_FUNCTION_ALLOW_BUILTIN=cryptoestiver definida (nos «task runners», definida nos runners). Guarda o segredowhsec_numa variável de ambiente do n8n e lê-a como no exemplo; se a tua instalação bloquear o acesso a variáveis no nó de código, guarda-o de outra forma que ela permita.
A lógica é a do exemplo «Node, à mão» da página das ferramentas HTTP. Troca YOUR_TOOL_ID pelo id da tua ferramenta:
// Code node, "Run Once for All Items".
// The Webhook node needs the option "Raw Body" (the exact body is then in the binary field "data").
// n8n must allow crypto in the Code node: NODE_FUNCTION_ALLOW_BUILTIN=crypto.
const { createHmac, timingSafeEqual } = require("crypto");
function verifyAtendia(secret, rawBody, headers, idPrefix) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures) return false;
// 5 minutes either way. "!(x <= 300)" also refuses a timestamp that is not a number.
if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300)) return false;
// Tool: "atd_tool_<your tool id>_". Post-call webhook: "atd_postcall_<your agent id>_".
if (!id.startsWith(idPrefix)) return false;
const key = Buffer.from(secret.slice("whsec_".length), "base64");
const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();
// During a rotation there are two entries; one match is enough.
return signatures.split(" ").some((entry) => {
const [version, value] = entry.split(",");
if (version !== "v1" || !value) return false;
const received = Buffer.from(value, "base64");
return received.length === expected.length && timingSafeEqual(received, expected);
});
}
const rawBody = (await this.helpers.getBinaryDataBuffer(0, "data")).toString("utf8");
const headers = $input.first().json.headers;
const ok = verifyAtendia($env.ATENDIA_SIGNING_SECRET, rawBody, headers, "atd_tool_YOUR_TOOL_ID_");
if (!ok) throw new Error("Invalid Atendia signature");
return [{ json: rawBody ? JSON.parse(rawBody) : {} }]; // a GET has no body
Zapier
- O «Webhooks by Zapier» (Catch Hook) responde logo que recebe o pedido, antes de o Zap correr. A resposta não leva o resultado do Zap.
- Por isso o Zapier serve só para enviar dados (por exemplo o webhook pós-chamada). Não o uses numa ferramenta de que o agente precisa de uma resposta com dados.
- Numa ferramenta de escrita, o 200 do Zapier quer dizer «recebido», não «feito». O agente pode dizer ao cliente que ficou feito sem o estar.
Verificar a assinatura
- O n8n verifica a assinatura num nó de código, com o exemplo acima.
- O Make e o Zapier não têm verificação HMAC própria. A alternativa honesta é um cabeçalho fixo e secreto: na ferramenta, junta um cabeçalho (por exemplo
X-Atendia-Key) do tipo «Secret» com um valor longo e aleatório, e no cenário ou no Zap recusa os pedidos em que o cabeçalho não bate. - Um cabeçalho fixo é mais fraco do que a assinatura: prova que quem chama conhece o valor, não liga o pedido ao corpo nem à hora. Troca-o se achares que foi exposto.
- A assinatura continua a ser enviada nos pedidos, se a organização tiver um segredo. Podes ignorá-la nestes serviços.
- No Make, um filtro que para o cenário não dá erro: o pedido com a chave errada recebe
200e o texto «Accepted», e a execução conta para os créditos da conta. Os dados ficam protegidos. Escolhe os campos da resposta na ferramenta: sem eles, o agente lê «Accepted» como resultado; com eles, esse200conta como falha, também no teste da ferramenta. - O Make oferece uma chave própria ao criar o webhook: em «API Key authentication» › «Add API key» › «Create a keychain», inventas uma chave em «API key value». Na ferramenta, junta o cabeçalho
x-make-apikeydo tipo «Secret» com a mesma chave. Serve em vez do cabeçalho fixo com filtro.
Para o resto da ferramenta (dados, erros, assinatura), vê a página das ferramentas HTTP.