Webhooks

Webhooks são o jeito recomendado de acompanhar a conversa em tempo real: em vez de consultar GET /v1/whatsapp/messages/{id} repetidamente, a Superlead envia um POST para a sua URL a cada transição de status, a cada mensagem recebida de um lead e a cada mensagem que a sua equipe envia pelo app do WhatsApp. É assim que se resolve o caso clássico do WhatsApp: a Meta aceita um envio fora da janela de 24 horas (201 accepted) e o falha segundos depois, de forma assíncrona — a falha chega no seu webhook, com o motivo.

Configuração

Cadastre seu endpoint

No painel da Superlead, em Integrações → Webhooks, adicione a URL HTTPS que vai receber os eventos.

Guarde o signing secret

Na criação, você recebe um signing secret (whsec_...) — ele é exibido nesse momento; guarde em local seguro. É com ele que você verifica a autenticidade de cada entrega.

Responda 2xx rápido

Ao receber um evento, responda 2xx imediatamente e processe de forma assíncrona. Entregas sem 2xx são reenviadas automaticamente com backoff.

Evento `whatsapp.message.updated`

Disparado a cada transição de status de uma mensagem enviada: sent, delivered, read ou failed — um evento por transição.

{
  "id": "evt_8c1f2a9b4d6e4f0a9b1c2d3e4f5a6b7c",
  "type": "whatsapp.message.updated",
  "channel": "whatsapp",
  "apiVersion": "v1",
  "createTime": "2026-07-03T19:03:12.000Z",
  "messageUpdated": {
    "wamid": "wamid.HBgMNTU1MzgxNTYwMzQ5FQIAERgU...",
    "status": "failed",
    "recipient": "+555381560349",
    "timestamp": "2026-07-03T19:03:11.000Z",
    "error": { "title": "Re-engagement message", "code": 131047 }
  }
}

Correlação: o wamid é o mesmo retornado por POST /v1/whatsapp/messages — use-o para casar o evento com o envio no seu sistema.
error: presente apenas quando status é failed. O code é o código numérico da Meta — o mesmo que aparece como upstream_code em GET /v1/whatsapp/messages/{id}. Para os significados, veja o catálogo de erros.
Para status de sucesso (sent, delivered, read), error vem null.

Evento `whatsapp.message.received`

Disparado quando um lead envia mensagem para o seu número. Exemplo com texto:

{
  "id": "evt_9f8e7d6c-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "type": "whatsapp.message.received",
  "channel": "whatsapp",
  "apiVersion": "v1",
  "createTime": "2026-07-03T14:30:00.000Z",
  "message": {
    "id": "msg_9f8e7d6c-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "wamid": "wamid.HBgMNTU...",
    "wabaId": "1234567890",
    "from": "+5511999999999",
    "fromUserId": null,
    "customerProfile": { "name": "João Silva" },
    "to": "+5511888888888",
    "sendTime": "2026-07-03T14:29:58.000Z",
    "type": "text",
    "text": { "body": "Olá! Quero saber mais." }
  }
}

Conforme o type, o corpo traz o bloco correspondente no lugar de text: image/video/document (com link, mimeType, caption), audio (com voice), location, contacts ou interactive (resposta de botão/lista). Mensagens vindas de anúncios click-to-WhatsApp incluem também o bloco referral com os dados da campanha (sourceId, headline, ctwaClid, ad, campaign).

Receber whatsapp.message.received também é o sinal de que a janela de 24 horas reabriu para aquele lead — a partir dali, mensagens de texto livre voltam a ser aceitas.

Evento `whatsapp.message.sent`

Disparado quando alguém da sua equipe envia mensagem a um lead pelo app WhatsApp Business ou pelo WhatsApp Web/desktop (número em modo coexistência). É o sinal de que um humano está na conversa. Envios feitos pela sua própria integração via POST /v1/whatsapp/messages não geram este evento — você já sabe o que enviou, e o acompanhamento de entrega chega pelo whatsapp.message.updated.

{
  "id": "evt_9b41c7d2e8f04a31b6c5...",
  "type": "whatsapp.message.sent",
  "channel": "whatsapp",
  "apiVersion": "v1",
  "createTime": "2026-07-04T12:00:00.000Z",
  "message": {
    "id": "msg_9b41c7d2e8f04a31b6c5...",
    "wamid": "wamid.HBgMNTUzMTk1NDM4OTA5FQIAERgS...",
    "wabaId": "1335330130855960",
    "from": "+553198101038",
    "to": "+553195438909",
    "toUserId": null,
    "sender": { "type": "human", "via": "whatsapp_app", "id": null, "name": null },
    "sendTime": "2026-07-04T11:59:58.000Z",
    "type": "text",
    "text": { "body": "Oi! Consigo te atender agora." }
  }
}

Direção: from é o seu número conectado à Superlead e to é o telefone do lead — o espelho exato do whatsapp.message.received.
Correlação: use message.to para casar o evento com o lead no seu sistema (por exemplo, GET /v1/leads?phone=...).
Corpo por tipo: mesmos blocos do received — text, image, video, audio, document, sticker, location e contacts. Para video e document, o campo link vem omitido (o arquivo ainda não foi processado pela Superlead).

O objeto `sender`

Identifica quem enviou a mensagem:

Campo	Valores atuais	Descrição
`type`	`human`	Quem agiu. Valores novos (por exemplo, `automation`) podem surgir no futuro — programe por igualdade (`type === "human"`), nunca por exclusão.
`via`	`whatsapp_app`, `superlead`	Origem do envio: app WhatsApp Business (inclui WhatsApp Web/desktop pareados) ou o chat do painel da Superlead (em breve).
`id`, `name`	—	Identidade do atendente, preenchida quando `via` é `superlead`. Em `whatsapp_app` vêm `null` — o WhatsApp não informa quem digitou.

Caso de uso: pausar seu bot quando um humano assume. Ao receber whatsapp.message.sent com sender.type === "human", pause as respostas automáticas para aquele message.to por um período (30 minutos, por exemplo) — um atendente entrou na conversa.

Verificando a assinatura

Cada entrega vem assinada nos headers svix-id, svix-timestamp e svix-signature (infraestrutura Svix — mesmo padrão usado por Clerk, Resend e outros). Verifique com a biblioteca da sua linguagem e o signing secret do endpoint:

import { Webhook } from "svix";

const wh = new Webhook(process.env.SUPERLEAD_WEBHOOK_SECRET);
// rawBody: corpo CRU da requisição (string), antes de qualquer JSON.parse
const event = wh.verify(rawBody, {
  "svix-id": req.headers["svix-id"],
  "svix-timestamp": req.headers["svix-timestamp"],
  "svix-signature": req.headers["svix-signature"],
});

from svix.webhooks import Webhook

wh = Webhook(os.environ["SUPERLEAD_WEBHOOK_SECRET"])
# payload: corpo cru da requisição (bytes/str), antes do json.loads
event = wh.verify(payload, headers)

Rejeite entregas com assinatura inválida. Sem a verificação, qualquer um que descubra sua URL pode forjar eventos.

Boas práticas

Idempotência: reentregas acontecem (é a garantia de “pelo menos uma vez”). Use o id do evento (evt_...) como chave de deduplicação no seu lado.
Ordem não garantida: um delivered pode chegar depois de um read. Use o timestamp do evento, não a ordem de chegada.
Webhook + polling: para fluxos críticos, combine os dois — webhook como caminho principal e GET /v1/whatsapp/messages/{id} como reconciliação periódica.

Comece aqui

Conceitos

Configuração

Evento `whatsapp.message.updated`

Evento `whatsapp.message.received`

Evento `whatsapp.message.sent`

O objeto `sender`

Verificando a assinatura

Boas práticas

​Configuração

​Evento whatsapp.message.updated

​Evento whatsapp.message.received

​Evento whatsapp.message.sent

​O objeto sender

​Verificando a assinatura

​Boas práticas

Configuração

Evento `whatsapp.message.updated`

Evento `whatsapp.message.received`

Evento `whatsapp.message.sent`

O objeto `sender`

Verificando a assinatura

Boas práticas