Guias

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-apikey ou por um endereço hook.….make.com, e o n8n pelo cabeçalho x-n8n-key ou 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-key e 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 Accepted sem 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 200 com 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ável NODE_FUNCTION_ALLOW_BUILTIN=crypto estiver definida (nos «task runners», definida nos runners). Guarda o segredo whsec_ 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:

javascript
// 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 200 e 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, esse 200 conta 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-apikey do 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.