> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metricaas.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> O Metricaas avisa o seu sistema quando algo acontece: lead novo, mudança de etapa, venda, mensagem. Como cadastrar, validar a assinatura e receber sem perder nem duplicar.

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.

```
evento no Metricaas  →  fila de entregas  →  POST https://seu-sistema/...  →  2xx = entregue
```

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](#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](#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.

> [!NOTE]
>
> As duas telas aparecem só para quem gerencia as conexões da empresa. Se você não as
> encontra, peça a essa pessoa.

> [!WARNING]
>
> 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**:

| Liberado | Cobre | Não cobre |
| - | - | - |
| `exemplo.com.br` | `exemplo.com.br`, `api.exemplo.com.br`, `n8n.api.exemplo.com.br` | `exemplo.com`, `outroexemplo.com.br` |
| `n8n.exemplo.com.br` | `n8n.exemplo.com.br` | `exemplo.com.br`, `api.exemplo.com.br` |

Pode digitar como vier — `https://API.Exemplo.com.br/hooks` vira `api.exemplo.com.br`.
IP não é aceito como domínio.

> [!WARNING]
>
> **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

| Evento | Quando sai |
| - | - |
| `lead.created` | Um lead novo entrou — por mensagem, link, anúncio, formulário de captação ou cadastro manual. |
| `lead.stage_changed` | O lead mudou de etapa no funil, pela pessoa ou por automação. |
| `lead.won` | O lead entrou numa etapa de **Ganho**. |
| `lead.lost` | O lead entrou numa etapa de **Perdido** (traz o motivo). |
| `lead.updated` | Nome, telefone, campos personalizados, tags ou responsável mudaram. |
| `message.received` | O lead mandou mensagem, num dos canais que o webhook escolheu. |
| `message.sent` | Saiu uma mensagem para o lead — da equipe, de um fluxo, de um agente pela API, ou do celular —, num dos canais que o webhook escolheu. |
| `flow.entered` | Um lead entrou num fluxo publicado (traz o fluxo, a versão, o post e o comentário que o puseram lá). |
| `flow.finished` | O caminho do lead num fluxo terminou — com o motivo. |
| `comment.received` | Alguém comentou num post do Instagram da empresa (o texto limpo, o post e o autor). |

Os campos de cada um, com exemplos completos, estão em
[Eventos e campos](https://docs.metricaas.com.br/conceitos/eventos-e-campos.md).

### 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.*`.

| | WhatsApp marcado | Instagram marcado | os dois |
| - | - | - | - |
| `message.*` de uma conversa do WhatsApp | recebe | não recebe | recebe |
| `message.*` de uma DM do Instagram | não recebe | recebe | recebe |
| `lead.*`, `flow.*`, `comment.received` | recebe | recebe | recebe |

* **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.

> [!WARNING]
>
> **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.

> [!WARNING]
>
> `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:

```json theme={null}
{
  "event": "message.received",
  "sent_at": "2026-10-21T14:03:12.481Z",
  "data": { "…": "os campos do evento" }
}
```

| Campo | O que é |
| - | - |
| `event` | O nome do evento — o mesmo do cabeçalho `X-Metricaas-Event`. |
| `sent_at` | Quando o **evento** foi gerado, em UTC. Não muda nas novas tentativas. |
| `data` | O conteúdo. Lead completo em `lead.*`; a mensagem em `message.*`. |
| `test` | Só existe no evento do botão **enviar teste**, e vale `true`. |

### Os cabeçalhos

| Cabeçalho | Exemplo | Para que serve |
| - | - | - |
| `X-Metricaas-Event` | `message.received` | Rotear sem abrir o corpo. |
| `X-Metricaas-Timestamp` | `1792591392` | Segundos Unix **desta tentativa**. Entra na assinatura. |
| `X-Metricaas-Signature` | `sha256=9f2c…` | HMAC-SHA256 do corpo — ver abaixo. |
| `X-Metricaas-Delivery` | `5b8f0d0e-…` | Id da entrega. **Igual em todas as tentativas** do mesmo evento para o mesmo webhook. |

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 é:

```
assinatura = "sha256=" + hex( HMAC-SHA256( segredo, "<X-Metricaas-Timestamp>.<corpo cru>" ) )
```

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.

> [tab] Node.js (Express)
>
> ```js theme={null}
> const crypto = require('crypto');
> const express = require('express');
> const app = express();
>
> const SEGREDO = process.env.METRICAAS_WEBHOOK_SECRET; // whsec_...
>
> app.post('/metricaas', express.raw({ type: 'application/json' }), (req, res) => {
>   const ts = req.header('X-Metricaas-Timestamp') || '';
>   const recebida = req.header('X-Metricaas-Signature') || '';
>
>   const esperada = 'sha256=' + crypto
>     .createHmac('sha256', SEGREDO)
>     .update(ts + '.' + req.body.toString('utf8'))
>     .digest('hex');
>
>   const a = Buffer.from(esperada);
>   const b = Buffer.from(recebida);
>   if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
>     return res.sendStatus(401); // não veio do Metricaas
>   }
>   if (!/^\d+$/.test(ts) || Date.now() / 1000 - Number(ts) > 300) {
>     return res.sendStatus(401); // carimbo velho: possível repetição
>   }
>
>   res.sendStatus(200); // responda já...
>   const { event, data } = JSON.parse(req.body.toString('utf8'));
>   setImmediate(() => processar(event, data, req.header('X-Metricaas-Delivery'))); // ...e processe depois
> });
>
> app.listen(3000);
> ```

> [tab] Python (Flask)
>
> ```python theme={null}
> import hashlib, hmac, os, time
> from flask import Flask, request, abort
>
> app = Flask(__name__)
> SEGREDO = os.environ["METRICAAS_WEBHOOK_SECRET"].encode()  # whsec_...
>
> @app.post("/metricaas")
> def metricaas():
>     ts = request.headers.get("X-Metricaas-Timestamp", "")
>     recebida = request.headers.get("X-Metricaas-Signature", "")
>     corpo = request.get_data()  # bytes crus
>
>     esperada = "sha256=" + hmac.new(SEGREDO, ts.encode() + b"." + corpo, hashlib.sha256).hexdigest()
>     # em BYTES: com str, um cabeçalho com caractere não-ASCII faz o compare_digest
>     # lançar TypeError, e o servidor responde 500 em vez de 401
>     if not hmac.compare_digest(esperada.encode(), recebida.encode("latin-1", "replace")):
>         abort(401)  # não veio do Metricaas
>     if not ts.isdigit() or time.time() - int(ts) > 300:
>         abort(401)  # carimbo velho: possível repetição
>
>     # enfileire o processamento e responda já
>     return "", 200
> ```

> [!NOTE]
>
> 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](https://docs.metricaas.com.br/receitas/agente-de-ia-com-n8n.md#verificar-a-assinatura).

## 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:

| Tentativa | Sai depois da anterior |
| - | - |
| 1 | — (em segundos, logo que o evento acontece) |
| 2 | 30 s |
| 3 | 1 min |
| 4 | 2 min |
| 5 | 4 min |
| 6 | 8 min |
| 7 | 16 min |
| 8 | 32 min |

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.

> [!NOTE]
>
> 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.

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.