Webhooks

Um webhook é uma URL do seu sistema que o Vamo chama com um POST quando algo acontece: uma mensagem foi entregue, um pedido mudou de etapa, a Meta aprovou um modelo. Assim você não precisa ficar consultando a API.

Como funcionaCopiar link desta seção

1. Você cadastra uma URL https:// e escolhe os eventos.
2. Quando um evento acontece, o Vamo envia um POST com um JSON assinado.
3. O seu servidor responde com um status 2xx em até 10 segundos.
4. Qualquer outra resposta (inclusive 3xx), ou nenhuma, é uma falha, e o Vamo tenta de novo.

Você cadastra o endpoint no Vamo, em Desenvolvedores → Webhooks → Adicionar webhook, ou pela API com POST /webhooks. O Segredo de assinatura aparece uma única vez, ao criar.

EventosCopiar link desta seção

Assine os eventos um a um, ou "*" para todos. Repare em que situação cada um dispara: vários só refletem o que foi feito pela API.

Em template.approved e template.rejected, o ID do modelo pode vir em id ou em templateId, conforme o caminho por onde a Meta avisou: leia os dois.

O que chega no seu servidorCopiar link desta seção

O corpo é sempre { event, data, timestamp }:

{
  "event": "message.delivered",
  "data": {
    "messageId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "conversationId": "5e4d3c2b-1a09-4f8e-8d7c-6b5a49382716",
    "waMessageId": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABEYEjQ1",
    "status": "delivered",
    "errorCode": null,
    "errorMessage": null,
    "timestamp": "2026-10-31T13:20:09.000Z"
  },
  "timestamp": "2026-10-31T13:20:10.412Z"
}

Mais um exemplo, um pedido enviado ao cliente:

{
  "event": "order.updated",
  "data": {
    "order": {
      "id": "8192a3b4-c5d6-4e7f-9a8b-92a3b4c5d6e7",
      "contactId": "2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f",
      "status": "shipped",
      "total": 462400,
      "currency": "BRL",
      "source": "api",
      "updatedAt": "2026-10-31T16:00:00.000Z"
    }
  },
  "timestamp": "2026-10-31T16:00:00.871Z"
}

Os objetos contact, conversation, message e order têm os mesmos campos das respostas da API. Campos novos podem aparecer: ignore os que você não conhece.

CabeçalhosCopiar link desta seção

Verificar a assinaturaCopiar link desta seção

Verifique toda entrega antes de confiar nela. A chave do HMAC é o segredo inteiro, com o prefixo whsec_. Calcule sobre o corpo exatamente como chegou (os bytes crus, antes de qualquer JSON.parse), compare em tempo constante e recuse entregas assinadas há mais de 5 minutos: assim uma requisição capturada não pode ser repetida depois.

import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.VAMO_WEBHOOK_SECRET; // "whsec_..."
const TOLERANCE_SECONDS = 300;
const app = express();

function verify(rawBody, timestamp, signature) {
  if (!timestamp || !signature) return false;
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", SECRET).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// express.raw: o corpo chega como Buffer, sem ser reescrito
app.post("/webhooks/vamo", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  const ok = verify(rawBody, req.get("X-Webhook-Timestamp"), req.get("X-Webhook-Signature-V2"));
  if (!ok) return res.status(401).send("assinatura inválida");

  const { event, data } = JSON.parse(rawBody);
  const deliveryId = req.get("X-Vamo-Delivery-Id");
  // Responda logo e processe depois (fila); ignore deliveryId já processado
  res.sendStatus(200);
  enqueue({ deliveryId, event, data });
});

Integrações antigas que verificam X-Webhook-Signature (HMAC só do corpo) continuam funcionando, mas essa assinatura não protege contra repetição. Prefira a V2.

Repetições, duplicatas e ordemCopiar link desta seção

• Tentativas. Uma entrega que falha é tentada de novo até 5 vezes, com espera crescente de cerca de 1, 2, 4, 8 e 16 segundos entre elas: 6 tentativas no total, que terminam em um ou dois minutos. Depois disso, aquele evento não é reenviado: ele fica no histórico de entregas como falha.
• Duplicatas. Se o seu servidor processou mas respondeu tarde (mais de 10 segundos) ou com erro, a mesma entrega chega de novo com o mesmo X-Vamo-Delivery-Id. Guarde os IDs já processados e ignore os repetidos.
• Responda rápido. Grave o evento numa fila e responda 200 antes de processar.
• Ordem. Cada entrega é independente: um message.delivered pode chegar antes do message.created da mesma mensagem. Use os timestamps.

Desativação depois de 3 diasCopiar link desta seção

Se um endpoint passar 3 dias sem nenhuma entrega bem-sucedida (contando da primeira falha depois do último sucesso), o Vamo o desativa:

• status vira disabled e os eventos seguintes não são enviados a ele, nem depois.
• O proprietário da organização recebe um e-mail com a URL e o último erro, e a página do webhook no Vamo mostra o motivo.
• Ele só volta pelo botão Testar e reativar, na página do webhook no Vamo: o Vamo envia um evento ping assinado ({ "event": "ping", "deliveryId": "…", "data": {}, "timestamp": "…" }) e, se o seu servidor responder 2xx, o endpoint volta a active. Pela API não dá para reativar.

Um endpoint que você pausou (inactive) nunca é desativado, mas também não recebe nada: os eventos do período em que ficou pausado se perdem.

Requisitos da URLCopiar link desta seção

• https://, num endereço público da internet. localhost, IPs de rede privada, nomes internos, serviços como nip.io e URLs com usuário e senha são recusados, ao cadastrar e a cada entrega.
• Redirecionamentos não são seguidos: um 301 ou 302 conta como falha.
• Do corpo da sua resposta, só o primeiro 1 KB fica no histórico.

Gerenciar pela APICopiar link desta seção

Todas estas rotas pedem uma chave secreta. As que alteram pedem acesso Leitura e escrita.

GET /webhooks/eventsCopiar link desta seção

A lista de eventos que podem ser assinados.

curl https://vamo.ai/api/v1/webhooks/events \
  -H "Authorization: Bearer sk_live_SUA_CHAVE"

{
  "data": [
    "contact.created", "contact.updated", "contact.deleted",
    "conversation.created", "conversation.updated", "conversation.closed",
    "message.created", "message.sent", "message.delivered", "message.failed",
    "campaign.created", "campaign.sent", "campaign.failed",
    "template.approved", "template.rejected",
    "order.created", "order.updated",
    "store.connected", "store.disconnected"
  ]
}

POST /webhooksCopiar link desta seção

Cadastra um endpoint.

curl -X POST https://vamo.ai/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://erp.lojaaurora.com.br/webhooks/vamo", "events": ["order.created", "order.updated", "message.failed"] }'

Resposta 201

{
  "data": {
    "id": "a3b4c5d6-e7f8-4a9b-8c0d-b4c5d6e7f8a9",
    "url": "https://erp.lojaaurora.com.br/webhooks/vamo",
    "secret": "whsec_4f1a9c2e7b3d8f6a0c5e9b2d7f4a1c8e3b6d9f2a5c8e1b4d",
    "events": ["order.created", "order.updated", "message.failed"],
    "status": "active",
    "createdAt": "2026-10-31T17:00:00.000Z"
  }
}

O secret só aparece nesta resposta. Guarde-o agora; se perder, gere outro com rotate-secret.

GET /webhooks e GET /webhooks/:idCopiar link desta seção

Os endpoints da organização (não paginado), ou um só. Sem o segredo.

{
  "data": [
    {
      "id": "a3b4c5d6-e7f8-4a9b-8c0d-b4c5d6e7f8a9",
      "url": "https://erp.lojaaurora.com.br/webhooks/vamo",
      "events": ["order.created", "order.updated", "message.failed"],
      "status": "active",
      "failureCount": 0,
      "lastDeliveryAt": "2026-10-31T16:00:01.000Z",
      "createdAt": "2026-10-31T17:00:00.000Z"
    }
  ]
}

status é active, inactive (pausado por você) ou disabled (desativado pelo Vamo). failureCount conta as tentativas que falharam desde o último sucesso.

PATCH /webhooks/:idCopiar link desta seção

Muda url, events ou status (active ou inactive). Mande só o que muda.

curl -X PATCH https://vamo.ai/api/v1/webhooks/a3b4c5d6-e7f8-4a9b-8c0d-b4c5d6e7f8a9 \
  -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["*"] }'

Responde 200 com o endpoint. Num endpoint disabled, mudar o status responde 409 com "code": "webhook_disabled_test_first"; url e events continuam editáveis.

DELETE /webhooks/:idCopiar link desta seção

Exclui o endpoint. Responde { "data": { "success": true } }.

POST /webhooks/:id/rotate-secretCopiar link desta seção

Gera um novo segredo e responde { "data": { "id": "…", "secret": "whsec_…" } }. O segredo antigo para de valer na hora, inclusive nas novas tentativas de entregas que estavam falhando. Atualize o seu servidor logo em seguida.

GET /webhooks/:id/deliveriesCopiar link desta seção

As 100 tentativas de entrega mais recentes, da mais nova para a mais antiga. Cada tentativa é uma linha.

{
  "data": [
    {
      "id": "d6e7f8a9-b0c1-4d2e-9f3a-e7f8a9b0c1d2",
      "deliveryId": "5b0f6c1e-8a39-4d0e-9a4e-2f1d7c3b9e10",
      "endpointId": "a3b4c5d6-e7f8-4a9b-8c0d-b4c5d6e7f8a9",
      "eventType": "order.updated",
      "payload": { "order": { "id": "8192a3b4-c5d6-4e7f-9a8b-92a3b4c5d6e7", "status": "shipped" } },
      "responseStatus": 200,
      "responseBody": "ok",
      "attempts": 1,
      "createdAt": "2026-10-31T16:00:01.000Z"
    }
  ]
}

payload é o data do evento, attempts o número da tentativa e deliveryId o mesmo valor do cabeçalho X-Vamo-Delivery-Id. Sem resposta do seu servidor, responseStatus é null e responseBody traz o erro de rede.

ErrosCopiar link desta seção

Os erros vêm no formato de sempre: { "error": { "code": "…", "message": "…" } }.

POST /webhooks aceita Idempotency-Key: repetir com a mesma chave devolve o mesmo endpoint (e o mesmo secret), sem criar outro.