Visão geral dos webhooks

Os webhooks notificam seu sistema em tempo real sobre o que acontece em cada sessão do WhatsApp não oficial: mensagens recebidas e enviadas, mudanças de status, eventos de conexão, atualizações de chats/contatos e movimentações em grupos.

Configuração por sessão

Cada sessão tem sua própria configuração de webhooks, com dois modos de entrega:

single — uma única URL para todos os eventos

Todos os eventos habilitados da sessão são enviados para a mesma URL. Útil quando um único endpoint concentra o processamento.

per_event — uma URL por evento

Cada evento tem sua própria webhookUrl, permitindo rotear eventos diferentes para endpoints diferentes.

Independente do modo, cada evento possui:

enabled

boolean

Liga ou desliga o envio do evento. Eventos desabilitados não são enviados.

webhookUrl

string

URL de destino do evento (no modo per_event) ou herdada da configuração única (no modo single).

Envelope comum

Todo webhook chega com o mesmo envelope. O conteúdo específico de cada evento fica em data.

{
  "event": "messages.received",
  "sessionId": "my-session",
  "data": { "...": "específico do evento" },
  "timestamp": "2026-01-24T22:51:32.601Z",
  "traceId": "c17dee440402792623e3ad6d925cb000"
}

event

string

required

Nome do evento (ex: messages.received).

sessionId

string

required

ID da sessão que originou o evento.

data

object

required

Conteúdo específico do evento. Veja a página de cada evento.

timestamp

string

required

Data e hora do envio em ISO 8601 (UTC).

traceId

string

Identificador para rastreamento ponta a ponta. Útil em logs e suporte.

Headers

Header	Valor
`Content-Type`	`application/json`
`User-Agent`	`Deliverify-Webhook/1.0`

Este produto não envia assinatura HMAC nos webhooks. Para restringir a origem, recomendamos usar uma URL secreta (com token no path) e/ou validar o User-Agent e o sessionId esperado.

Entrega e confiabilidade

Retentativas (7 tentativas, backoff exponencial)

Em caso de falha, a entrega é repetida até 7 vezes com backoff exponencial: aproximadamente 5s, 10s, 20s, 40s, 80s e 160s entre as tentativas.

Falhas permanentes (404 / 410)

Respostas HTTP 404 ou 410 são tratadas como falha permanente: a entrega não é mais retentada para aquela URL.

Timeout

Cada tentativa tem timeout de 30 segundos. Endpoints lentos podem ser considerados falha e entrar em retentativa.

Circuit breaker

Há um circuit breaker por URL: URLs que falham repetidamente são temporariamente interrompidas para evitar sobrecarga.

Deduplicação

Eventos passam por deduplicação via Redis (TTL de 5 minutos), reduzindo entregas duplicadas do mesmo evento em curto intervalo.

Responda rapidamente com um status 2xx. Faça o processamento pesado de forma assíncrona (fila/worker) e confirme o recebimento o quanto antes para evitar timeouts (30s) e retentativas desnecessárias.

Eventos disponíveis

Evento	Descrição	Página
`messages.received`	Mensagem recebida	messages.received
`messages.sent`	Mensagem enviada pela sessão	messages.sent
`message.read`	Mensagem lida	Status de mensagens
`message.delivered`	Mensagem entregue	Status de mensagens
`message.deleted`	Mensagem apagada	Status de mensagens
`message.update`	Mensagem atualizada/editada	Status de mensagens
`connection.qrcode`	QR code gerado	Conexão
`connection.paircode`	Código de pareamento gerado	Conexão
`connection.status`	Mudança de status da conexão	Conexão
`logged_out`	Sessão deslogada	Conexão
`chats.update`	Atualização de chat	Chats, contatos e presença
`chats.upsert`	Chat criado/atualizado	Chats, contatos e presença
`contacts.update`	Atualização de contato	Chats, contatos e presença
`contacts.upsert`	Contato criado/atualizado	Chats, contatos e presença
`presence`	Presença (online/digitando)	Chats, contatos e presença
`groups_participants.join`	Entrada em grupo	Grupos
`groups_participants.leave`	Saída de grupo	Grupos
`groups_participants.promote`	Promoção a admin	Grupos
`groups_participants.demote`	Rebaixamento de admin	Grupos
`group_participants.join-request`	Solicitação de entrada	Grupos
`group_participants.join-request.revoked`	Solicitação revogada	Grupos
`group_participants.join-request.approved`	Solicitação aprovada	Grupos
`labels.edit`	Etiqueta criada/editada/excluída	Etiquetas
`labels.association.chat`	Etiqueta aplicada/removida de uma conversa	Etiquetas
`labels.association.message`	Etiqueta aplicada/removida de uma mensagem	Etiquetas
`appstate.label.edit`	Etiqueta (sincronização completa)	Etiquetas
`appstate.label.association.chat`	Etiqueta em conversa (sincronização completa)	Etiquetas
`appstate.label.association.message`	Etiqueta em mensagem (sincronização completa)	Etiquetas
`call.offer`	Chamada de voz recebida	Chamadas (VoIP)
`call.accepted`	Chamada de entrada atendida	Chamadas (VoIP)
`call.rejected`	Chamada de entrada rejeitada	Chamadas (VoIP)
`call.ringing`	Chamada de saída tocando	Chamadas (VoIP)
`call.connected`	Chamada de saída conectada	Chamadas (VoIP)
`call.ended`	Chamada de saída encerrada	Chamadas (VoIP)
`call.audio`	Áudio da chamada (chunks ou gravação)	Chamadas (VoIP)
`history.message.upsert`	Mensagem do histórico (apenas RabbitMQ)	Histórico e sincronização
`history.message.received`	Mensagem recebida do histórico (apenas RabbitMQ)	Histórico e sincronização
`history.messages.sent`	Mensagem enviada do histórico (convertida no webhook)	Histórico e sincronização
`history_sync`	Conclusão/resumo do backfill	Histórico e sincronização
`appstate.agent.update`	Dispositivo/agente vinculado atualizado	Histórico e sincronização

Introdução

Assistente de Integração

Ligações

Webhooks

Visão geral dos webhooks

Configuração por sessão

Envelope comum

Headers

Entrega e confiabilidade

Eventos disponíveis

​Configuração por sessão

​Envelope comum

​Headers

​Entrega e confiabilidade

​Eventos disponíveis

Configuração por sessão

Envelope comum

Headers

Entrega e confiabilidade

Eventos disponíveis