Skip to main content
A API responde quando você pergunta. O webhook é o caminho inverso: quando algo acontece no Metricaas, mandamos um POST para a URL do seu sistema — um n8n, um ERP, um agente de IA.
A entrega é durável: o evento vira uma linha numa fila e só sai dela quando o seu endpoint responde 2xx — ou quando esgotamos as tentativas. Se o seu sistema estiver fora do ar por alguns minutos, nada se perde.

Cadastrar

1

Libere o domínio do seu sistema

Abra Configurações → Domínios liberados (na navegação nova, Conexões → aba Domínios) e adicione o domínio para onde os eventos vão.É a empresa dizendo “autorizo mandar os meus dados para este endereço”. Sem domínio liberado, o cadastro do webhook é recusado.
2

Cadastre o webhook

Em Configurações → Webhooks (navegação nova: Conexões → aba Webhooks), clique em criar, cole a URL e marque os eventos que você quer receber — e, se assinar mensagens, de quais canais (WhatsApp, Instagram ou os dois; veja Os canais das mensagens).A URL precisa ser https://. http, localhost, IP de rede interna e nome sem ponto são recusados.
3

Copie o segredo

Cada webhook ganha um segredo (whsec_…), visível no cartão dele com o botão copiar. É com ele que você confere que a chamada veio do Metricaas — veja Validar a assinatura.
4

Envie um teste

O botão enviar teste enfileira uma entrega de verdade — mesma assinatura, mesmo retry. Em segundos ela aparece em últimas entregas, com o status que o seu endpoint devolveu.
As duas telas aparecem só para quem gerencia as conexões da empresa. Se você não as encontra, peça a essa pessoa.
O evento de teste é sempre um lead.created, com "test": true no envelope e dados de exemplo — mesmo que o webhook só assine message.*. Se o seu fluxo filtra por evento, ele vai descartar o teste; está certo. Se não filtra, trate o test: true antes de gravar qualquer coisa.

Domínios liberados

A regra de casamento é por domínio e todos os subdomínios dele: Pode digitar como vier — https://API.Exemplo.com.br/hooks vira api.exemplo.com.br. IP não é aceito como domínio.
Libere o subdomínio exato quando o domínio pai não é seu. Se o seu n8n roda em suaempresa.app.n8n.cloud, libere suaempresa.app.n8n.cloud — e não app.n8n.cloud, que cobriria o n8n de qualquer outra pessoa.
O que acontece se o domínio sair da lista depois. A lista é conferida duas vezes: no cadastro e em cada entrega. Se alguém remover o domínio com o webhook já criado, a próxima entrega não é feita: ela fica como desistiu, com o motivo “o domínio deste destino não está liberado para esta empresa” no cartão do webhook. Não há nova tentativa — liberar o domínio de novo faz os próximos eventos saírem, não os que foram recusados. A tela de Domínios liberados lista os webhooks que ficaram sem domínio, para a causa e o sintoma aparecerem juntos.

Os eventos

Os campos de cada um, com exemplos completos, estão em Eventos e campos.

Os canais das mensagens

Cada webhook escolhe de quais canais recebe as mensagens: WhatsApp, Instagram ou os dois. O canal é o da conversa, e ele vem em data.channel (whatsapp ou instagram) em todo message.*.
  • O padrão é só WhatsApp, inclusive nos webhooks cadastrados antes desta opção existir (03/11/2026). O Instagram é escolha sua, na tela do webhook.
  • Os eventos lead.*, flow.* e comment.received não são filtrados. Eles são do lead, e o mesmo lead pode ter conversa no WhatsApp e no Instagram. O canal do payload de lead é o canal de atribuição (de onde a pessoa veio), não o da conversa.
  • É preciso marcar pelo menos um canal.
Agente de IA: marque o Instagram só se o seu agente foi feito para responder lá. Um agente de WhatsApp que recebe DM do Instagram responde no Instagram — com o tom, os links e as regras do WhatsApp.

A regra do histórico

Quando um número de WhatsApp é conectado, o WhatsApp sincroniza as conversas antigas dele. Essas mensagens chegam ao Metricaas, mas não viram message.received nem message.sent: elas aconteceram semanas atrás, e um “mensagem nova” para cada uma dispararia resposta automática, notificação e SLA no seu sistema. O lead que nasce dessas conversas sai como lead.created — ele passou a existir no Metricaas agora. Ele vem com origem_historico: true e com created_at na data da mensagem original, que pode ser de semanas atrás.
origem_historico diz de onde o lead veio, e vale para sempre: num lead.won desse mesmo lead meses depois, ele continua true. Não escreva “se origem_historico, ignore o evento” — você descartaria uma venda real.

O que chega

O envelope

Todo evento tem a mesma casca:

Os cabeçalhos

O Content-Type é application/json e o User-Agent é Metricaas-Webhook/1.

Validar a assinatura

Sem validar, qualquer pessoa que descubra a sua URL injeta lead falso no seu sistema — ou, num agente de IA, faz o agente mandar mensagem para quem ela quiser. A conta é:
Três cuidados, e cada um fecha um buraco:
  1. Use o corpo cru, exatamente os bytes que chegaram. Parsear o JSON e serializar de novo pode mudar um byte e a assinatura não confere.
  2. Compare em tempo constante (timingSafeEqual), não com ===.
  3. Recuse carimbo com mais de 5 minutos. O carimbo entra no HMAC justamente para isso: sem ele, quem capturar uma entrega válida pode repeti-la para sempre.
O carimbo é o da tentativa, não o do evento: uma nova tentativa 30 minutos depois chega com carimbo novo e passa na janela de 5 minutos. Para saber a idade do evento, use sent_at do envelope.
No n8n, o corpo cru exige uma opção do nó Webhook — o passo a passo está na receita Agente de IA com n8n.

Entrega e novas tentativas

Entregue é 2xx. Qualquer outra resposta é falha — inclusive 3xx: não seguimos redirecionamento, porque seguir é como o payload acaba num endereço que você não controla mais. Se a sua URL mudou, edite o webhook. Cada tentativa espera a resposta por até 10 segundos; depois disso conta como “sem resposta dentro do tempo”. Quando falha, tentamos de novo com o intervalo dobrando a cada vez: São 8 tentativas no total, cobrindo pouco mais de uma hora. Se a oitava falhar, a entrega fica como desistiu e não sai mais. O cartão do webhook mostra a última falha e quando foi a última entrega que deu certo.
Desligar um webhook pausa a fila dele; as entregas pendentes saem quando você o religa. Remover o webhook descarta as pendentes.

Do seu lado: o que torna o recebimento seguro

Responda 200 na hora; processe depois

Os 10 segundos são para responder, não para trabalhar. Se o seu endpoint chama um LLM, consulta outra API ou grava em três lugares antes de responder, um dia ele passa de 10 s — e aí recebe o mesmo evento de novo, ainda processando o primeiro. Responda assim que a assinatura conferir e jogue o trabalho numa fila (ou, no n8n, no modo Respond: Immediately). A partir daí, uma falha no seu processamento é sua para tratar: o Metricaas já considerou o evento entregue.

Seja idempotente com X-Metricaas-Delivery

A entrega é pelo menos uma vez. Se o seu servidor processou e a resposta se perdeu no caminho (timeout, conexão caiu), a gente não tem como saber, e manda de novo. O X-Metricaas-Delivery é o mesmo em todas as tentativas: guarde os que você já processou e ignore a repetição.
Se o seu processamento chama a API do Metricaas para responder uma mensagem, use o metricaas_message_id da mensagem recebida como base da Idempotency-Key (ex.: resposta:<metricaas_message_id>). Ele é o mesmo em toda repetição da mesma mensagem — inclusive quando o WhatsApp reentrega o evento e nós geramos uma entrega nova, com outro X-Metricaas-Delivery. Assim uma repetição não manda a resposta duas vezes, mesmo que o seu lado não tenha guardado nada.

Não confie na ordem

As entregas saem na ordem em que ficam prontas, e uma nova tentativa pode passar à frente de um evento mais novo. Para ordenar, use os carimbos de dentro de data (received_at nas mensagens), não a ordem de chegada.