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, a cada mensagem que a sua equipe envia pelo app do WhatsApp, a cada mudança de status de um template (aprovação, recusa, pausa) e a cada lead criado, alterado ou excluído. É 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.

Evento `whatsapp.template.updated`

Disparado a cada mudança de status avisada pela Meta sobre um template da sua conta: aprovação, recusa, pausa, exclusão. É o jeito de saber que um template criado ou editado foi aprovado, sem consultar a API. Mudanças na nota de qualidade (quality score) e na categoria do template não são enviadas como este evento.

{
  "id": "evt_tpl.1689556908129832.REJECTED.1791295392",
  "type": "whatsapp.template.updated",
  "channel": "whatsapp",
  "apiVersion": "v1",
  "createTime": "2026-10-06T14:03:12.000Z",
  "templateUpdated": {
    "id": "tpl_1689556908129832",
    "name": "confirmacao_consulta",
    "language": "pt_BR",
    "category": "UTILITY",
    "event": "REJECTED",
    "rejectedReason": "INVALID_FORMAT",
    "rejectionInfo": {
      "reason": "Your template has parameters placed next to each other without text or punctuation between them.",
      "recommendation": "Separate parameters with descriptive text and ensure each parameter is clearly contextualized."
    }
  }
}

Correlação: templateUpdated.id é o mesmo tpl_... das rotas /v1/whatsapp/templates/{id}.
category: a categoria atual na Meta — pode ser diferente da que você pediu na criação. Pode ser null quando a Meta não informa.
rejectedReason e rejectionInfo: presentes na recusa; null nos demais eventos. Mesmo num evento REJECTED, rejectionInfo pode vir null quando a Meta não envia a explicação. O texto de rejectionInfo vem da Meta e costuma estar em inglês.

`event`	Significado
`APPROVED`	Aprovado: já pode ser enviado.
`REJECTED`	Recusado. Edite o template para reenviar à análise.
`PENDING`	Em análise pela Meta.
`PAUSED`	Pausado pela Meta por baixa qualidade.
`DISABLED`	Desabilitado pela Meta por feedback negativo.
`FLAGGED`	Recebeu feedback negativo e corre risco de ser desabilitado. Continua enviável.
`REINSTATED`	Deixou de estar sinalizado ou desabilitado: pode ser enviado de novo.
`IN_APPEAL`	Em recurso de uma recusa.
`PENDING_DELETION`	Exclusão solicitada; ainda há mensagens em entrega.
`DELETED`	Excluído.
`ARCHIVED`, `UNARCHIVED`	Arquivado por inatividade; restaurado.
`LOCKED`	Bloqueado para edição.
`LIMIT_EXCEEDED`	A conta atingiu o limite de templates.

event não é o status do template. Alguns valores (FLAGGED, REINSTATED, LOCKED) são avisos, não status. Para decidir se um template pode ser enviado, trate APPROVED, REINSTATED e FLAGGED como “pode” (em FLAGGED a qualidade caiu e o template pode ser pausado) ou consulte GET /v1/whatsapp/templates/{id}. Valores novos podem surgir — ignore os que não conhecer.

Endpoints cadastrados antes deste evento não o recebem automaticamente: edite o endpoint em Integrações → Webhooks e marque Template Atualizado.

Eventos de lead

Os eventos lead.created, lead.updated e lead.deleted mantêm um sistema externo (CRM, dashboard, planilha) em dia com os seus leads sem consultar a API em laço.

Evento	Quando
`lead.created`	Um lead foi criado — por mensagem recebida, pelo painel, pela API ou por formulário.
`lead.updated`	Mudou algum campo do lead que a API expõe: nome, telefone, origem, canal, ponto de entrada, etapa do funil, documento ou endereço. Uma mensagem nova do lead, sozinha, não gera este evento.
`lead.deleted`	O lead foi excluído.

{
  "id": "evt_lead.updated.0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f.20261016120000123456",
  "type": "lead.updated",
  "channel": null,
  "apiVersion": "v1",
  "createTime": "2026-10-16T12:00:01.204Z",
  "lead": {
    "id": "lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "name": "João Silva",
    "phone": "+5511999999999",
    "source": "Meta Ads",
    "channel": "WhatsApp",
    "entryPoint": "ctwa",
    "funnelStage": "Qualificado",
    "document": null,
    "documentType": null,
    "cep": null,
    "address": null,
    "addressNumber": null,
    "addressComplement": null,
    "neighborhood": null,
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "createdAt": "2026-06-01T12:00:00.000000Z",
    "updatedAt": "2026-10-16T12:00:00.123456Z"
  }
}

lead é o mesmo recurso de GET /v1/leads/{id}, com as chaves em camelCase (entry_point vira entryPoint) e mais updatedAt. Em lead.created o formato é o mesmo.
Estado atual: o evento traz o lead como ele está no momento do envio, não só o que mudou. Grave pelo lead.id; se dois eventos chegarem fora de ordem, fique com o de maior updatedAt.
channel do envelope é null: eventos de lead não pertencem a um canal. O canal de origem do lead está em lead.channel.
lead.deleted traz só o id:

{
  "id": "evt_lead.deleted.0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "type": "lead.deleted",
  "channel": null,
  "apiVersion": "v1",
  "createTime": "2026-10-16T12:05:00.000Z",
  "lead": { "id": "lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f" }
}

Os eventos de lead são opcionais: em Integrações → Webhooks, marque a categoria Leads no endpoint. Endpoints que já existiam não passam a recebê-los sozinhos.

Webhook é de melhor esforço. Para não perder nada, combine com a sincronização incremental: os eventos deixam o seu sistema em dia na hora, e uma passada periódica de GET /v1/leads?updated_since= (por exemplo, uma vez por dia) cobre qualquer evento que não tenha chegado.

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. O evento de template não tem timestamp: use o createTime (hora da emissão do evento). Nos eventos de lead, use lead.updatedAt.
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`

Evento `whatsapp.template.updated`

Eventos de lead

Verificando a assinatura

Boas práticas

​Configuração

​Evento whatsapp.message.updated

​Evento whatsapp.message.received

​Evento whatsapp.message.sent

​O objeto sender

​Evento whatsapp.template.updated

​Eventos de lead

​Verificando a assinatura

​Boas práticas

Configuração

Evento `whatsapp.message.updated`

Evento `whatsapp.message.received`

Evento `whatsapp.message.sent`

O objeto `sender`

Evento `whatsapp.template.updated`

Eventos de lead

Verificando a assinatura

Boas práticas