Webhooks

15. Webhooks#

Webhooks permitem receber eventos em tempo real via HTTP POST no seu servidor.

Semantica de entrega: pelo menos uma vez (at-least-once). Retries do worker, falhas de rede ou retry manual podem gerar o mesmo event_id mais de uma vez. O endpoint do cliente deve ser idempotente e deduplicar por event_id (ou pelo par webhook_id + event_id).

Ordem em relação ao banco (tenant): para message.delivered, message.read, message.played, message.deleted e message.edited, o Catcher aplica primeiro o UPDATE na tabela messages do tenant e em seguida enfileira/dispara webhooks e streams em tempo real — o estado persistido não fica atrás do envio do evento HTTP.

POST/v1/webhooks#

Cria um novo webhook.

Auth: Owner, Admin

Request:

{
  "url": "https://meuservidor.com/webhook",
  "instance_id": "84c2e480-...",
  "events": "message.received,message.sent",
  "secret": "whsec_minha_chave_compartilhada"
}

Escopo do webhook — por instância vs global:

• Por instância: defina instance_id para receber eventos apenas daquela instância. Recomendado quando cada instância envia para um backend diferente.
• Global: omita instance_id (ou envie vazio) para receber eventos de todas as instâncias da empresa no mesmo endpoint.
• Cuidado com duplicacao: se você criar um webhook global E um por instância apontando para o mesmo URL, os eventos daquela instância serao entregues duas vezes (uma por cada webhook). Prefira um ou outro.

Eventos disponíveis:

Resposta 201:

{
  "id": 1,
  "url": "https://meuservidor.com/webhook",
  "secret": "a1b2c3d4e5f6...64_hex_chars",
  "events": "message.received,message.sent",
  "active": true
}

O secret e gerado automaticamente e usado para assinar os payloads via HMAC-SHA256. A URL e validada no cadastro/edicao e revalidada no momento da entrega; destinos internos ou resolvidos para rede privada são rejeitados. O secret aparece somente na resposta de criação. GET, LIST e PATCH nunca o reexibem. A entrega e https only por padrão. Em runtime você pode afrouxar isso com WEBHOOK_ALLOW_INSECURE_HTTP=true ou restringir dominios com WEBHOOK_ALLOWED_DOMAINS / WEBHOOK_BLOCKED_DOMAINS.

Email verificado obrigatório: o cadastro de webhook exige que a conta já tenha confirmado o email — uma conta recem-criada e ainda não verificada recebe 403.

Respostas de erro:

GET/v1/webhooks#

Lista todos os webhooks da empresa.

Auth: Owner, Admin

Resposta 200:

[
  {
    "id": 1,
    "url": "https://meuservidor.com/webhook",
    "events": "message.received,message.sent",
    "active": true,
    "created_at": "2026-03-07T10:00:00Z"
  }
]

GET/v1/webhooks/{webhookId}#

Retorna detalhes de um webhook.

Auth: Owner, Admin (superadmin tem acesso cross-company — ver "Webhook detail endpoints" no fim da seção de feeds)

Resposta 200: Objeto webhook sem o campo secret.

PATCH/v1/webhooks/{webhookId}#

Atualiza um webhook.

Auth: Owner, Admin (superadmin tem acesso cross-company — ver "Webhook detail endpoints" no fim da seção de feeds)

Request:

{
  "url": "https://novo-servidor.com/webhook",
  "events": "*",
  "active": false,
  "secret": "whsec_rotacionado_manual"
}

Todos os campos são opcionais.

Resposta 200: Objeto webhook atualizado sem o campo secret.

DELETE/v1/webhooks/{webhookId}#

Remove um webhook.

Auth: Owner, Admin (superadmin tem acesso cross-company — ver "Webhook detail endpoints" no fim da seção de feeds)

Resposta 204: Sem corpo.

GET/v1/webhooks/{webhookId}/logs#

Lista logs de entrega do webhook.

Retencao e privacidade: registros de entrega com sucesso são removidos após 7 dias; falhas permanecem 14 dias (tarefa periodica webhook:cleanup_logs). Em cada execução, linhas com mais de 48 horas passam por redacao: o campo payload da API vira um JSON enxuto com event_type, event_id e redacted: true; copia completa do corpo enviado ao cliente e apagada no armazenamento interno; respostas HTTP muito longas são truncadas. Novas linhas já gravam em payload apenas metadados (tipo, id, tamanho do JSON). O retry manual depende dessa copia original: quando payload_raw já tiver sido limpo, o reenvio não e mais permitido.

Auth: Owner, Admin (superadmin tem acesso cross-company — ver "Webhook detail endpoints" no fim da seção de feeds)

Query Parameters:

Resposta 200:

{
  "data": [
    {
      "id": 1,
      "webhook_id": 1,
      "event_id": "evt-abc-123",
      "event_type": "message.received",
      "payload": "{...}",
      "payload_raw": "{...}",
      "status_code": 200,
      "response": "OK",
      "success": true,
      "attempt": 1,
      "error_class": "",
      "created_at": "2026-03-07T12:00:00Z"
    }
  ],
  "total": 25,
  "page": 1,
  "limit": 50
}

Erro 404 (WEBHOOK_NOT_FOUND): webhook inexistente ou de outra empresa.

POST/v1/webhooks/{webhookId}/logs/{logId}/retry#

Reenvia um evento que falhou.

Auth: Owner, Admin (superadmin tem acesso cross-company — ver "Webhook detail endpoints" no fim da seção de feeds) Regras: so aceita logs com success=false e com payload_raw ainda preservado. Logs já entregues com sucesso ou já redatados retornam 409 Conflict.

Resposta 202:

{
  "status": "retrying",
  "event_id": "evt_xxxx"
}

GET/v1/webhooks/stuck#

Lista entregas webhook falhadas que precisam de atenção, agregadas por event_id (uma linha por evento, com a contagem total de tentativas e a classe do erro).

Auth: Owner, Admin Escopo: somente webhooks da company autenticada.

Query params (todos opcionais):

Resposta 200:

{
  "data": [
    {
      "log_id": 123,
      "webhook_id": 7,
      "webhook_url": "https://app.exemplo.com/webhook",
      "event_id": "evt-abc-123",
      "event_type": "message.received",
      "status_code": 503,
      "response": "service unavailable",
      "attempts": 25,
      "error_class": "transient_5xx",
      "is_hard_failed": false,
      "has_payload_raw": true,
      "created_at": "2026-04-08T15:30:45Z"
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 50
}

is_hard_failed=true indica que o evento bateu em SkipRetry por ser permanent_4xx após 3 tentativas — provavelmente um bug de configuração (URL errada, secret expirado, parser quebrado). has_payload_raw=false indica que o payload_raw foi redatado ou nunca foi salvo, e não da pra reenviar via API.

POST/v1/webhooks/retry-bulk#

Re-enfileira em batch um conjunto de entregas falhadas. Aceita dois modos:

Modo 1 — explicito por log IDs:

{
  "log_ids": [123, 124, 125]
}

Modo 2 — por filtro:

{
  "webhook_id": 7,
  "event_type": "message.received",
  "class": "transient_5xx",
  "since": "2026-04-07T00:00:00Z"
}

Auth: Owner, Admin Escopo: somente webhooks da company autenticada (logs de outros tenants são silenciosamente pulados). Limites: máximo de 500 retries por chamada. Eventos com payload_raw vazio são pulados. Re-enfileiramento e deduplicado por event_id.

Resposta 202:

{
  "requeued": 7,
  "skipped": 1,
  "errors": ["log 199: payload unavailable"]
}

Estrategia de retry e classificação de erros#

Quando uma entrega falha, o Catcher classifica o erro e aplica a estrategia de retry adequada:

Schedule de retry (default WEBHOOK_MAX_RETRY=30, configuravel por env):

n=1   → 5s
n=2   → 15s
n=3   → 30s
n=4   → 1min
n=5   → 2min
n=6   → 5min
n=7   → 10min
n=8   → 15min
n=9   → 30min
n>=10 → 1h (capped)

Janela total: ~22 horas. Cobre restart de serviço, manutenção planejada, picos de carga e blips de infraestrutura sem perder eventos.

Wake-up retry on success: quando uma entrega chega com sucesso a um webhook, o Catcher automaticamente re-enfileira todos os eventos falhados (excluindo permanent_4xx) desse mesmo webhook nas últimas 24h. Isso acelera a recuperacao quando o consumer volta de um restart — você não precisa esperar o backoff exponencial drainar. Um Redis lock por webhook (60s TTL) evita thundering herd.

Persistencia de payload_raw: entregas falhadas mantem o payload original não redatado pelo periodo de retencao completo (14 dias), de modo que retry manual via UI ou via POST /v1/webhooks/retry-bulk continue funcionando para eventos antigos.

Verificação de assinatura HMAC#

Cada requisição webhook inclui X-Catcher-Timestamp e X-Catcher-Signature. A assinatura HMAC-SHA256 cobre a string timestamp + "." + raw_body, usando o secret do webhook.

Validação recomendada no receiver:

• rejeite timestamps com skew maior que 5 minutos
• use comparacao constant-time (hmac.compare_digest, crypto.timingSafeEqual, subtle.ConstantTimeCompare)
• deduplicate por event_id porque a entrega e at-least-once

Headers enviados pelo Catcher:

Content-Type: application/json
User-Agent: Catcher-Webhook/1.0
X-Catcher-Timestamp: 1711035600
X-Catcher-Signature: sha256=<hmac_hex>

Validação (exemplo em Python):

import hmac
import hashlib
import time

def verify_signature(payload_body, secret, timestamp, signature_header):
    now = int(time.time())
    ts = int(timestamp)
    if abs(now - ts) > 300:
        return False
    signed = f"{timestamp}.".encode() + payload_body
    expected = "sha256=" + hmac.new(
        secret.encode(), signed, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Validação (exemplo em Node.js):

const crypto = require('crypto');

function verifySignature(payloadBody, secret, timestamp, signatureHeader) {
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) {
    return false;
  }
  const signed = Buffer.concat([
    Buffer.from(`${timestamp}.`),
    Buffer.isBuffer(payloadBody) ? payloadBody : Buffer.from(payloadBody)
  ]);
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signed)
    .digest('hex');
  if (expected.length !== signatureHeader.length) {
    return false;
  }
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Payloads dos eventos#

Todos os eventos seguem a estrutura base:

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "message.received",
  "instance_id": "84c2e480-...",
  "timestamp": "2026-03-07T15:30:45.123Z",
  "data": { ... }
}

Troubleshooting — se o seu consumer responde 400 Bad Request: "missing event fields" ou "malformed envelope", o parser do receiver está esperando uma chave de envelope com nome diferente do que o Catcher envia (tipicamente event em vez de type). A correção e no consumer: leia body.type (não body.event). Cheque também se o consumer usa express.raw() (ou equivalente) para preservar os bytes exatos do body — JSON.parse + JSON.stringify muda a ordem das chaves e quebra a verificação HMAC (veja seção anterior).

Campos de mutualidade (is_mutual / mutuality_checked_at) — todos os eventos que carregam um phone também podem trazer is_mutual (bool) e mutuality_checked_at (string ISO-8601). is_mutual=true significa que o contato resolvido tem a instância salva na agenda dele (lido do cache contact_mutuality_cache, sem roundtrip extra com o Meta). Ambos são omitidos quando a resposta não está em cache — permite distinguir "não-mutuo" de "desconhecido".

message.received#

Disparado quando uma mensagem e recebida no WhatsApp. Persistido na tabela messages. Para mensagens de mídia (image, video, audio, document, sticker), o arquivo e baixado do WhatsApp, armazenado no S3 e um registro Media e criado. O campo media_id pode ser usado para baixar a mídia via GET /v1/instances/{instanceId}/media/{mediaId}. Mensagens de status@broadcast e ecos da própria instância (IsFromMe) não geram esse evento.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "sender_lid": "216251804708983:34@lid",
  "chat_lid": "216251804708983@lid",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "type": "audio",
  "content": "",
  "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mime_type": "audio/ogg; codecs=opus",
  "file_size": 34567,
  "duration": 15,
  "quoted_msg_id": "d28b6749-0a5c-47bc-9c12-fd4537a5d149",
  "timestamp": 1741360245,
  "is_group": false,
  "push_name": "Joao Silva"
}

Exemplo de mensagem de grupo:

{
  "phone": "554199999999",
  "from": "554199999999@s.whatsapp.net",
  "chat": "120363025555555555@g.us",
  "message_ids": ["76089f45-b309-43eb-9f2b-198ce302aa28"],
  "type": "text",
  "content": "oi pessoal",
  "timestamp": 1741360245,
  "is_group": true,
  "push_name": "Joao Silva",
  "group_name": "Vendas 2026",
  "group_subject": "Time comercial"
}

Para grupos: chat e o JID do grupo (@g.us), from/phone/push_name identificam o participante que enviou, e group_name/group_subject descrevem o grupo. Veja Mensagens de Grupo para o padrão completo.

Exemplo com contexto de anuncio (Instagram/Facebook click-to-WhatsApp):

{
  "phone": "554188322497",
  "from": "554188322497@s.whatsapp.net",
  "chat": "554188322497@s.whatsapp.net",
  "message_ids": ["ACDFD74C4368A916E0FE"],
  "type": "text",
  "content": "Ola! Tenho interesse no tratamento com o iModel",
  "ad_context": {
    "source_type": "instagram",
    "source_app": "Instagram",
    "source_id": "ad-123",
    "title": "Tratamento iModel",
    "body": "Agende sua consulta agora",
    "media_type": "image",
    "ctwa_clid": "ARA...",
    "ref": "utm_campaign_xyz",
    "thumbnail_url": "https://media.catcher.one/biazap_abc/ads/thumbs/7a3b1c...d.jpg",
    "media_url": "https://media.catcher.one/biazap_abc/ads/media/91ef02...c.mp4"
  },
  "is_forwarded": false,
  "timestamp": 1741360245,
  "is_group": false,
  "push_name": "Patricia"
}

Exemplo de contato compartilhado (type=contact):

{
  "phone": "554196332719",
  "from": "554196332719@s.whatsapp.net",
  "chat": "554196332719@s.whatsapp.net",
  "message_ids": ["b1e2c3d4-5678-90ab-cdef-1234567890ab"],
  "type": "contact",
  "content": "Amor",
  "contacts": [
    {
      "display_name": "Amor",
      "phones": ["5541988887777"],
      "vcard": "BEGIN:VCARD\nVERSION:3.0\nN:;Amor;;;\nFN:Amor\nTEL;type=CELL;type=VOICE;waid=5541988887777:+55 41 8888-7777\nEND:VCARD"
    }
  ],
  "timestamp": 1741360245,
  "is_group": false,
  "push_name": "Adriano"
}

Compartilhar varios contatos de uma vez (ou enviar via POST .../messages/contact com contacts: [...]) produz um ContactsArrayMessage: o mesmo evento type=contact com uma entrada em contacts por contato.

Este evento também pode trazer is_mutual / mutuality_checked_at — ver a nota de mutualidade no início desta seção.

Campos de ad_context (todos opcionais, presentes conforme disponível no proto):

Proxy-discipline (licoes #29, #31, #35): As URLs acima (thumbnail_url, media_url) são sempre URLs Catcher — seja URL pública do R2 (quando S3_PUBLIC_URL está configurado) ou vazio. O worker NUNCA expoe URLs brutas do Meta (cdninstagram.com, fbcdn.net, scontent.*, facebook.com/*/videos/*) ao consumer. Todas as imagens/videos de anuncios são baixados pelo proxy dedicado da instância e republicados via R2 com dedup por sha256 do conteúdo (mesma thumbnail em 100 instâncias da mesma empresa = 1 objeto no R2). O campo source_url do proto Meta (permalink do post Instagram/Facebook) permanece intencionalmente removido — consumidores podem reconstruir referência via source_id + source_type quando necessário. Cache e best-effort: uma falha de rede ou ausência de binding emite campo vazio, sem quebrar o webhook.

Campos de cada item de contacts (presente apenas quando type=contact):

Contatos: O campo top-level phone identifica quem enviou o cartao, não o contato compartilhado. Para os números do(s) contato(s) compartilhado(s), use contacts[].phones.

Reactions: Quando type=reaction, o campo content contem o emoji (ex: "❤️"). Um content vazio indica que a reaction foi removida. O campo reaction_target_id contem o ID da mensagem que recebeu a reaction.

message.sent#

Disparado após envio bem-sucedido de qualquer mensagem via API. Persistido na tabela messages. Para mensagens de mídia, inclui media_id para download via GET /v1/instances/{instanceId}/media/{mediaId}.

{
  "phone": "554192464230",
  "to": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "type": "image",
  "content": "Foto do produto",
  "media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mime_type": "image/jpeg",
  "file_name": "produto.jpg",
  "file_size": 123456,
  "source": "api",
  "idempotency_key": "msg-2026-03-21-0001",
  "quoted_msg_id": "3EB0AAA111BBB222",
  "timestamp": 1741360300,
  "is_group": false
}

Exemplo com varios contatos (type=contact):

{
  "phone": "554137984905",
  "to": "554137984905@s.whatsapp.net",
  "chat": "554137984905@s.whatsapp.net",
  "message_ids": ["c2b4e6f0-1234-4ab5-9c0d-fedcba987654"],
  "type": "contact",
  "content": "Suporte Catcher, Comercial",
  "contacts": [
    {
      "display_name": "Suporte Catcher",
      "phones": ["5541988887777"],
      "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Suporte Catcher\nTEL;type=CELL;type=VOICE;waid=5541988887777:+5541988887777\nEND:VCARD"
    },
    {
      "display_name": "Comercial",
      "phones": ["5541977776666"],
      "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Comercial\nTEL;type=CELL;type=VOICE;waid=5541977776666:+5541977776666\nEND:VCARD"
    }
  ],
  "source": "api",
  "idempotency_key": "msg-2026-05-18-0042",
  "timestamp": 1741360500,
  "is_group": false
}

content em type=contact: com um único contato, e o display_name. Com varios, e a juncao dos display_name separados por ", " (ex: "Suporte Catcher, Comercial"). Para os dados estruturados, sempre use contacts[].

Este evento também pode trazer is_mutual / mutuality_checked_at — ver a nota de mutualidade no início desta seção.

Captura de outbound externo: Mensagens enviadas por WhatsApp Web, pelo celular ou por outra API conectada ao mesmo número são capturadas automaticamente como message.sent com source: "external". Isso permite rastrear toda a comunicação outbound independente de onde foi originada. Mensagens enviadas pela própria Catcher via fila tem source: "api". A persistencia no banco também distingue: a coluna source na tabela messages armazena "api" ou "external". Em mensagens externas, quoted_msg_id e reaction_target_id também são preservados quando presentes, inclusive para message.sent de grupos (is_group=true).

LID em mensagens externas: Quando uma mensagem e enviada por outro dispositivo (WhatsApp Web, celular) para um contato cujo chat aparece como LID, a Catcher resolve o telefone usando 3 camadas de fallback:

1. RecipientAlt (protocolo): o WhatsApp envia peer_recipient_pn no evento, contendo o telefone do destinatário — está e a fonte primaria e mais confiavel para outbound echo.
2. MySQL (contact_identities): registro persistido de interacoes anteriores (SenderAlt, RecipientAlt, queries de contato).
3. SQLite (whatsmeow_lid_map): cache do whatsmeow populado por syncs de grupo, mensagens de migração LID, e operações de envio.

Se o contato já foi visto em qualquer dessas fontes, phone, to e chat conterao o telefone resolvido. Caso contrario, phone ficara vazio e chat_lid contera o LID original — quando o contato responder (trazendo SenderAlt) ou aparecer em um sync de grupo, o mapeamento LID→telefone será aprendido automaticamente para futuras consultas.

Nota: Não existe API no protocolo WhatsApp para resolver LID→telefone sob demanda. GetUserInfo(lid) não retorna o telefone (so funciona na direcao PN→LID).

message.delivered#

Disparado quando o destinatário recebe a mensagem (dois checks cinza). Atualiza status=delivered e delivered_at na tabela messages.

{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "sender_lid": "42812401807390:77@lid",
  "status": "delivered",
  "timestamp": 1741360310,
  "is_group": false
}

message.read#

Disparado quando o destinatário le a mensagem (dois checks azuis). Atualiza status=read e read_at na tabela messages.

{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "sender_lid": "42812401807390:77@lid",
  "status": "read",
  "timestamp": 1741360350,
  "is_group": false
}

message.played#

Disparado quando o destinatário abre uma mídia "visualizar uma vez" (view-once). Atualiza status=played e played_at na tabela messages.

{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "sender_lid": "42812401807390:77@lid",
  "status": "played",
  "timestamp": 1741360400,
  "is_group": false
}

message.deleted#

Disparado quando uma mensagem e apagada ("apagar para todos"). Atualiza status=deleted e deleted_at na tabela messages. Cobre ambas as direcoes: mensagens inbound apagadas pelo contato (is_from_me=false) e mensagens outbound apagadas pelo operador via WhatsApp phone/Web (is_from_me=true).

{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "sender_lid": "216251804708983:34@lid",
  "is_from_me": false,
  "timestamp": 1741360400
}

message.edited#

Disparado quando uma mensagem e editada. Atualiza content na tabela messages. Cobre ambas as direcoes: mensagens inbound editadas pelo contato (is_from_me=false) e mensagens outbound editadas pelo operador via WhatsApp phone/Web (is_from_me=true).

{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "sender_lid": "216251804708983:34@lid",
  "new_content": "Texto editado da mensagem",
  "is_from_me": false,
  "is_group": false,
  "push_name": "Joao",
  "timestamp": 1741360450
}

call.received#

Disparado quando a instância recebe uma chamada. Persistido na tabela call_logs.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "call_id": "CALL-ABC123",
  "timestamp": 1741360500
}

connection.update#

Disparado quando o status da conexão WhatsApp muda. Persistido na tabela instances.

{
  "status": "connected",
  "reason": "",
  "previous_status": "connecting",
  "ban_expiry": null
}

Novos status:

• connect_failure — falha ao conectar ao servidor WhatsApp (ex: erro de rede, autenticação falhou)
• client_outdated — versão do cliente WhatsApp está desatualizada e precisa ser atualizada
• stream_error — erro no stream de comunicação com o servidor WhatsApp
• keepalive_timeout — keepalive não recebeu resposta a tempo; conexão pode estar instável
• keepalive_restored — keepalive voltou a funcionar normalmente após um timeout

presence.update#

Disparado quando um contato fica online/offline ou está digitando. Evento transiente, não persistido no banco.

Nota: Para receber presença de digitacao, a instância precisa estar com presença available. Para presença online/offline, a Catcher so passa a monitorar após POST /v1/instances/{instanceId}/contacts/{contactId}/presence/subscribe.

Snapshot opcional: GET /v1/instances/{instanceId}/contacts/{contactId}/presence le o último estado conhecido em Redis (online, last_seen, typing_state). Isso não substitui SSE/WebSocket/webhook; e apenas um read model transiente para UX.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "available": true,
  "last_seen": 1741360000,
  "state": "composing",
  "is_chat": true,
  "chat": "554192464230@s.whatsapp.net",
  "is_group": false
}

group.update#

Disparado para qualquer mudanca em grupo. Persistido na tabela group_events.

{
  "group_jid": "120363025555555555@g.us",
  "group_name": "Vendas 2026",
  "group_subject": "Time comercial",
  "action": "participant_join",
  "sender": "554192464230@s.whatsapp.net",
  "timestamp": 1741360600,
  "value": "",
  "members": ["554199999999@s.whatsapp.net", "554188888888@s.whatsapp.net"]
}

Ações possíveis:

<a id="mensagens-de-grupo"></a>

Mensagens de Grupo (semantica + cache)

Quando uma mensagem chega de um grupo, os campos do payload tem a seguinte semantica:

Padrão de renderizacao: Para mostrar uma mensagem de grupo no estilo WhatsApp Web, use group_name como titulo da conversa e push_name como autor do balao individual. chat e o identificador único da conversa de grupo (sempre termina em @g.us).

Cache de metadados de grupo (lazy):

group_name e group_subject são populados a partir de um cache em memória por instância. O cache funciona assim:

1. Primeira mensagem de um grupo novo: o cache está vazio. O evento e emitido com group_name="" e group_subject="". Em paralelo, a Catcher dispara uma busca assincrona via GetGroupInfo para popular o cache.
2. Mensagens subsequentes: o cache já tem o nome, entao todos os eventos do mesmo grupo virao com group_name e group_subject preenchidos.
3. Eventos events.GroupInfo com name_change ou topic_change atualizam o cache imediatamente, antes mesmo de emitir o group.update correspondente.
4. Logout/delete da instância limpa o cache para evitar leakage entre sessões.

Quais eventos incluem group_name / group_subject?

Fallback para grupos novos: Se o seu consumidor recebe um evento de grupo com group_name vazio, você pode chamar GET /v1/instances/{instanceId}/groups/{groupJid} para resolver o nome no momento (e isso já vai popular o cache para os próximos eventos).

contact.update#

Disparado quando a foto de perfil, nome ou status de um contato muda. Persistido na tabela contact_events.

Quando o contato e identificado por LID (Linked Device ID), o campo jid mostra o JID do telefone (se resolvido) e jid_lid preserva o LID original. Se o LID não puder ser resolvido, jid contera o LID e phone ficara vazio.

{
  "phone": "554192464230",
  "jid": "554192464230@s.whatsapp.net",
  "jid_lid": "273293080838230@lid",
  "action": "picture_change",
  "value": "j+rE",
  "timestamp": 1741360700
}

Ações possíveis:

Avatar cache: Quando action e picture_change, a Catcher automaticamente baixa a nova foto do contato e armazena no S3/R2. Quando action e picture_remove, o cache e limpo. Clientes podem usar este evento para invalidar avatares em cache local e buscar a nova versão via GET /v1/instances/{instanceId}/contacts/{phone}/avatar.

instance.banned#

Disparado quando a instância recebe um ban temporario ou permanente do WhatsApp. Persistido nos campos ban_expiry e ban_reason da instância. Diferente de connection.update com status: "banned", este evento traz informações detalhadas do ban.

{
  "instance_id": "84c2e480-...",
  "permanent": false,
  "reason": "spam",
  "ban_expiry": 1741446000
}

Nota: O evento connection.update com status: "banned" também e emitido. Use instance.banned quando precisar de detalhes do ban (permanencia, motivo, expiracao).

instance.offline / instance.critical_offline / instance.recovered#

Eventos do monitor de saúde (internal/health/monitor.go). Disparados quando uma instância cruza um dos thresholds de tempo offline:

• instance.offline — instância desconectada ha 15min ou mais (transicao única do tier degraded para offline).
• instance.critical_offline — instância desconectada ha 6h ou mais (transicao do tier offline para critical_offline). Também dispara email para o owner da empresa + todos os superadmins.
• instance.recovered — instância voltou a conectar após ter ficado em offline/critical_offline (limpa o offline_alert_level).

Cada evento e disparado exatamente uma vez por transicao. O monitor armazena o nivel atual em offline_alert_level na linha da instância para evitar re-emissoes a cada scan (60s). Instâncias com desired_state=DISCONNECTED (pausadas manualmente) nunca disparam estes eventos.

{
  "instance_id": "84c2e480-...",
  "name": "EJ Whats",
  "phone": "554192464230",
  "tier": "critical_offline",
  "previous_tier": "offline",
  "status": "DISCONNECTED",
  "desired_state": "CONNECTED",
  "disconnected_at": "2026-04-06T21:44:00Z",
  "last_activity_at": "2026-04-06T21:42:18Z",
  "offline_duration_seconds": 158400,
  "offline_duration_human": "1d 20h",
  "reason": "",
  "timestamp": 1744156800
}

Configuração: Os thresholds (15min e 6h) são constantes no código (internal/health/tier.go) para garantir visibilidade em code review. Para tunar, edite OfflineThreshold e CriticalThreshold.

Endpoint relacionado: GET /v1/admin/instance-health retorna o rollup completo cross-tenant em tempo real (usado pelo banner do dashboard, badge da sidebar, e card "Saúde das instâncias").

message.undecryptable#

Disparado quando uma mensagem e recebida mas não pode ser decriptada pela instância. Isso pode acontecer quando a sessão de criptografia está dessincronizada ou quando a mensagem foi enviada para um dispositivo anterior. Persistido na tabela messages com status undecryptable.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["3EB0ABC123DEF456"],
  "is_unavailable": true,
  "unavailable_type": "account_removed",
  "decrypt_fail_mode": "",
  "timestamp": 1741360800
}

message.starred#

Disparado quando uma mensagem e marcada ou desmarcada com estrela. Evento de sincronização entre dispositivos; não persistido em tabela separada.

{
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "starred": true,
  "is_from_me": false,
  "timestamp": 1741360850
}

message.deleted_for_me#

Disparado quando uma mensagem e apagada localmente ("apagar para mim"), sem afetar os outros participantes. Diferente de message.deleted, que e "apagar para todos". Não persistido.

{
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "is_from_me": false,
  "timestamp": 1741360900
}

call.accepted#

Disparado quando uma chamada feita pela instância e aceita pela parte remota. Persistido na tabela call_logs.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "call_id": "CALL-ABC123",
  "timestamp": 1741360950
}

call.rejected#

Disparado quando uma chamada e rejeitada pela parte remota. Persistido na tabela call_logs.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "call_id": "CALL-ABC123",
  "timestamp": 1741361000
}

call.ended#

Disparado quando uma chamada e finalizada por qualquer motivo. Persistido na tabela call_logs.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "call_id": "CALL-ABC123",
  "reason": "normal",
  "duration": 45,
  "timestamp": 1741361050
}

call.group_offer#

Disparado quando a instância recebe uma chamada de grupo. Persistido na tabela call_logs.

{
  "call_id": "CALL-GRP456",
  "media": "audio",
  "type": "group",
  "timestamp": 1741361100
}

group.joined#

Disparado quando a instância e adicionada a um grupo (por convite, link ou admin). Persistido na tabela group_events.

{
  "group_jid": "120363025555555555@g.us",
  "group_name": "Vendas 2026",
  "group_topic": "Canal de vendas da equipe",
  "reason": "invite",
  "sender": "554192464230@s.whatsapp.net",
  "timestamp": 1741361150
}

blocklist.update#

Disparado quando a lista de contatos bloqueados e alterada. Não persistido.

{
  "action": "modify",
  "changes": [
    {
      "phone": "554192464230",
      "jid": "554192464230@s.whatsapp.net",
      "action": "block"
    },
    {
      "phone": "554188322497",
      "jid": "554188322497@s.whatsapp.net",
      "jid_lid": "216251804708983@lid",
      "action": "unblock"
    }
  ],
  "timestamp": 1741361200
}

Nota: Quando action e "set", a lista changes representa a lista completa de contatos bloqueados (todos com action: "block"). Quando e "modify", cada item em changes pode ser "block" ou "unblock".

contact.identity_changed#

Disparado quando um contato troca de dispositivo principal (re-registrou o WhatsApp em outro celular). A chave de criptografia do contato mudou. Persistido na tabela contact_events.

{
  "phone": "554192464230",
  "jid": "554192464230@s.whatsapp.net",
  "jid_lid": "273293080838230@lid",
  "implicit": false,
  "timestamp": 1741361250
}

contact.sync#

Disparado quando um contato e sincronizado do dispositivo (agenda de contatos). Persistido na tabela contact_events.

{
  "phone": "554192464230",
  "jid": "554192464230@s.whatsapp.net",
  "first_name": "Joao",
  "full_name": "Joao Silva",
  "timestamp": 1741361300
}

chat.pin#

Disparado quando um chat e fixado ou desfixado. Evento de sincronização entre dispositivos. Não persistido.

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "pinned": true,
  "timestamp": 1741361350
}

chat.archive#

Disparado quando um chat e arquivado ou desarquivado. Evento de sincronização entre dispositivos. Não persistido.

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "archived": true,
  "timestamp": 1741361400
}

chat.mute#

Disparado quando um chat e silenciado ou dessilenciado. Evento de sincronização entre dispositivos. Não persistido.

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "muted": true,
  "mute_end": 1741447800,
  "timestamp": 1741361450
}

chat.read_state#

Disparado quando um chat e marcado como lido ou não lido. Emitido tanto por sincronização entre dispositivos (AppState) quanto pelas APIs POST /v1/instances/{id}/mark-read (com mark_all: true) e POST /v1/instances/{id}/mark-unread. Não persistido.

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "marked_as_read": false,
  "timestamp": 1741361500
}

Nota: Quando disparado via API (mark-read / mark-unread), o evento e emitido imediatamente após o SendAppState bem-sucedido, sem esperar o echo de sincronização do WhatsApp.

chat.clear#

Disparado quando um chat e limpo (histórico apagado). Não persistido.

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "delete_media": false,
  "timestamp": 1741361550
}

chat.delete#

Disparado quando um chat e apagado completamente. Não persistido.

{
  "phone": "554192464230",
  "chat": "554192464230@s.whatsapp.net",
  "chat_lid": "216251804708983@lid",
  "delete_media": true,
  "timestamp": 1741361600
}

privacy.update#

Disparado quando as configurações de privacidade da instância são alteradas. Não persistido.

{
  "settings": {
    "group_add": "contacts",
    "last_seen": "everyone",
    "online": "match_last_seen",
    "profile_photo": "contacts",
    "status": "contacts",
    "read_receipts": "enabled",
    "call_add": "known"
  },
  "changed_fields": ["group_add", "profile_photo"],
  "timestamp": 1741361650
}

Configurações possíveis: group_add, last_seen, online, profile_photo, status, read_receipts, call_add. Os valores dependem da configuração (ex: "everyone", "contacts", "nobody", "match_last_seen", "enabled", "disabled", "known").

history.sync#

Disparado quando uma sincronização de histórico e recebida do servidor WhatsApp (tipicamente após conectar um novo dispositivo ou após POST /history/import). As mensagens do blob são persistidas no histórico de conversas; o evento abaixo e o resumo da importação.

{
  "sync_type": "RECENT",
  "conversation_count": 42,
  "message_count": 1500,
  "pushname_count": 38,
  "imported_count": 1480,
  "duplicate_count": 20,
  "skipped_count": 0,
  "failed_count": 0,
  "timestamp": 1741361700
}

Histórico importado não emite message.received/message.sent por mensagem, para evitar que consumidores processem mensagens antigas como tráfego novo. Use history.sync para progresso/resumo e GET /chats/{chatId}/messages para ler o conteúdo salvo.

sync.preview#

Disparado quando um preview de sincronização offline e recebido, indicando quantos eventos estão pendentes. Não persistido.

{
  "total": 250,
  "messages": 180,
  "receipts": 45,
  "notifications": 25,
  "timestamp": 1741361750
}

média.retry_result#

Disparado quando o resultado de um retry de download de mídia e recebido. Quando a mídia de uma mensagem recebida não pode ser baixada inicialmente, o WhatsApp pode reenviar os bytes — este evento indica o resultado dessa tentativa. Não persistido.

{
  "message_ids": ["3EB0ABC123DEF456"],
  "chat": "554192464230@s.whatsapp.net",
  "success": true,
  "timestamp": 1741361800
}

label.edit#

Disparado quando uma etiqueta e criada, editada ou removida. Etiquetas são um recurso do WhatsApp Business. Não persistido.

{
  "label_id": "5",
  "name": "Urgente",
  "color": 1,
  "deleted": false,
  "timestamp": 1741361850
}

label.chat_association#

Disparado quando um chat e associado ou desassociado de uma etiqueta. Não persistido.

{
  "label_id": "5",
  "chat": "554192464230@s.whatsapp.net",
  "phone": "554192464230",
  "associated": true,
  "timestamp": 1741361900
}

label.message_association#

Disparado quando uma mensagem e associada ou desassociada de uma etiqueta. Não persistido.

{
  "label_id": "5",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["3EB0ABC123DEF456"],
  "associated": true,
  "timestamp": 1741361950
}

message.acked#

Disparado quando outro dispositivo seu (sync multi-device) confirma recebimento de uma mensagem que você enviou. Distinto de message.delivered — aquele e o contato confirmando entrega; este e o seu próprio segundo aparelho. Não persistido (não carimba delivered_at na tabela messages).

{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "sender_lid": "42812401807390:77@lid",
  "status": "acked",
  "timestamp": 1741360305,
  "is_group": false
}

Este evento também pode trazer is_mutual / mutuality_checked_at — ver a nota de mutualidade no início desta seção.

message.read_other_device#

Disparado quando você le uma mensagem inbound em outro dispositivo seu. O contato não leu nada — e o seu próprio estado de leitura multi-device. Util para evitar re-notificar o operador de algo que ele já viu em outro aparelho. Não persistido (não carimba read_at, que e reservado para o receipt de leitura do contato sobre suas mensagens outbound).

{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "chat": "554192464230@s.whatsapp.net",
  "sender": "554192464230@s.whatsapp.net",
  "chat_lid": "42812401807390@lid",
  "sender_lid": "42812401807390:77@lid",
  "status": "read_other_device",
  "timestamp": 1741360360,
  "is_group": false
}

Este evento também pode trazer is_mutual / mutuality_checked_at — ver a nota de mutualidade no início desta seção.

connection.diagnostic#

Timeline fina do ciclo de conexão — emitido em pontos-chave do ConnectInstance do worker (dialing, QR emitido, WebSocket fechado, etc.). Usado pela modal de QR do frontend para mostrar exatamente o que está acontecendo em tempo real. Não persistido. Carrega apenas dados seguros (IP do proxy, sinais de ciclo de vida do whatsmeow, mensagens curtas) — nunca URLs de CDN do Meta, telefones de terceiros ou conteúdo de mensagem.

{
  "step": "qr_emitted",
  "level": "info",
  "message": "QR Code gerado, aguardando leitura",
  "detail": {
    "proxy_city": "sao-paulo"
  },
  "timestamp": 1741360100
}

contacts.bulk_imported#

Disparado quando o worker absorve um roster de contatos em massa de uma so vez — hoje apenas no HistorySync de INITIAL_BOOTSTRAP que segue um pareamento novo. CRMs podem usar isso como um único sinal "usuário acabou de parear, aqui estão os contatos" em vez de esperar o registro preencher incrementalmente. Não persistido como evento (os contatos em si vao para a tabela contacts).

{
  "source": "history_sync_initial_bootstrap",
  "imported": 312,
  "skipped": 4,
  "timestamp": 1741361000
}

sync.offline_completed#

Disparado quando o whatsmeow termina de absorver eventos perdidos que chegaram durante uma janela de Disconnected. count > 0 significa que houve um gap real de entrega — a instância agora tem dados novos que o consumer não viu em tempo real. count == 0 significa que a reconexao cobriu o gap sem tráfego perdido (saudável). Não persistido.

{
  "count": 7,
  "timestamp": 1741361050
}

connection.recovered_quick#

Disparado quando um Connected segue um Disconnected dentro de uma janela curta (~60s). Distinto de instance.recovered, que exige >=15min de offline observavel. Util para dashboards que querem rastrear ruido de estabilidade de conexão separadamente de outages reais. Não persistido.

{
  "duration_seconds": 12.4,
  "timestamp": 1741361080
}

Persistencia de eventos#

Eventos são persistidos no banco de dados do tenant quando indicado na tabela de eventos. Eventos transientes (chat., label., privacy.update, blocklist.update, sync.*, média.retry_result, message.starred, message.deleted_for_me) não são gravados em MySQL — são entregues apenas via webhook e SSE/WebSocket.

Ciclo de vida da mensagem na tabela messages:

queued → sent → delivered → read
                    ↓
                 deleted (se revogada)

Tabelas de eventos: