POST para a URL do seu sistema — um n8n, um
ERP, um agente de IA.
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.
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.
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 emdata.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.*ecomment.receivednão são filtrados. Eles são do lead, e o mesmo lead pode ter conversa no WhatsApp e no Instagram. Ocanaldo payload de lead é o canal de atribuição (de onde a pessoa veio), não o da conversa. - É preciso marcar pelo menos um canal.
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 virammessage.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.
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 é:- 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.
- Compare em tempo constante (
timingSafeEqual), não com===. - 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.
- Node.js (Express)
- Python (Flask)
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.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.
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 dedata
(received_at nas mensagens), não a ordem de chegada.