Visão geral

Em vez de perguntar de tempos em tempos se algo mudou, deixe a Amivu avisar. Um webhook é um POST assinado no seu endereço, no momento em que o fato acontece.

O envelope

Todo evento tem a mesma forma. É isso que permite um único tratador na sua ponta, despachando por type.

{
  "id": "evt_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "type": "message.received",
  "created_at": "2026-08-26T21:42:19.238Z",
  "environment": "live",
  "organization_id": "org_01K7ZFA5X8Q2M4N6P8R0T2V4W6",
  "data": {
    "message": { "object": "message", "id": "msg_01K7...", "text": "Oi!" },
    "conversation": { "object": "conversation", "id": "conv_01K7..." }
  }
}

Os objetos dentro de data são idênticos aos que um GET devolveria. Não há uma segunda forma de mensagem só para webhook — se houvesse, você escreveria dois analisadores para a mesma entidade.

Os cabeçalhos

X-Amivu-Signature   t=1756240000,v1=5257a869e7ecebeda32affa62cdca3fa...
X-Amivu-Event       message.received
X-Amivu-Delivery    whd_01K7ZFA5X8Q2M4N6P8R0T2V4W6
X-Amivu-Timestamp   1756240000

X-Amivu-Delivery identifica a tentativa; ele muda a cada reenvio. O que identifica o evento é o id no corpo, e é ele que você deve usar para deduplicar.

Como responder

Responda 2xx assim que receber. Qualquer outra coisa — inclusive 3xx — conta como falha e agenda uma reentrega.

Entrega é pelo menos uma vez

Um evento pode chegar duas vezes: a rede caiu depois de você responder, o processo reiniciou no meio. Não é defeito — é a garantia honesta de qualquer sistema de entrega.

Guarde o id do evento e ignore o que já viu. Uma tabela com o identificador e um índice único resolve, e é a mesma disciplina que a Amivu usa internamente.

app.post("/webhooks/amivu", async (req, res) => {
  // 1. confira a assinatura ANTES de olhar o corpo
  if (!assinaturaValida(req)) return res.status(401).end();

  // 2. responda logo — o processamento vem depois
  res.status(200).end();

  // 3. ignore o que já foi visto
  const evento = req.body;
  if (await jaProcessado(evento.id)) return;
  await enfileirar(evento);
});

Cadastrar um endpoint

Pelo painel, em Configurações → Desenvolvedores → Webhooks, ou pela API:

curl https://api.amivu.com.br/v1/webhooks \
  -H "Authorization: Bearer $AMIVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-sistema.com.br/webhooks/amivu",
    "description": "Sincronização com o ERP",
    "events": ["message.received", "message.failed", "conversation.closed"]
  }'

A resposta traz o secret inteiro — a única vez. O ambiente do endpoint vem da chave que o criou, e não do corpo: uma credencial de teste não consegue cadastrar um endpoint que receberá dados reais.

Continue em Assinaturas.