Eventos disponíveis

O PEPINO ZAP envia os eventos abaixo por webhook. Esta página é o catálogo de eventos: descreve o envelope comum a todos eles e, para cada evento, o objeto data exato que você recebe — campo a campo, com exemplos reais de payload.

Você cadastra os webhooks via API (POST /v1/webhooks), de forma self-service e escopada ao seu Projeto — veja Webhooks. Para validar que a entrega realmente veio do PEPINO ZAP, consulte Assinatura. Para o comportamento de timeout, reenvio e idempotência, consulte Entrega e retry. Os mesmos eventos e o mesmo envelope também chegam por WebSocket, se você preferir um transporte em tempo real sem expor um endpoint público.

Envelope comum

Toda entrega usa o método POST e sempre o mesmo envelope. Apenas o conteúdo de data muda de um evento para outro — o que permite escrever um único handler que primeiro lê event e só então interpreta data.

{
  "event": "message.received",
  "instanceId": "cm5x8a9k20001abc123def456",
  "timestamp": "2026-05-29T22:16:30Z",
  "data": {}
}

Campos do envelope:

Headers presentes em toda entrega:

Content-Type: application/json
User-Agent: pepino-zap-webhooks/1
X-Pepino-Event: message.received
X-Pepino-Webhook-Id: <id-do-webhook>
X-Pepino-Signature: sha256=<hmac-hex>

• X-Pepino-Event — repete o event do corpo. Útil para rotear a entrega antes de fazer parse do JSON.
• X-Pepino-Webhook-Id — identifica qual webhook cadastrado originou a entrega. É constante por webhook (o mesmo em todas as entregas), então não é uma chave de deduplicação; para deduplicar, use um identificador de negócio em data (como waMessageId). Ver Idempotência.
• X-Pepino-Signature — assinatura HMAC-SHA256 do corpo bruto, no formato sha256=<hmac-hex>. Permite verificar a autenticidade do que foi recebido. O cálculo está descrito em Assinatura.

message.received

Disparado quando a instância recebe uma mensagem com conteúdo.

{
  "event": "message.received",
  "instanceId": "cm5x8a9k20001abc123def456",
  "timestamp": "2026-05-29T22:16:30Z",
  "data": {
    "from": "5511999999999@s.whatsapp.net",
    "type": "image",
    "text": "Mensagem de teste",
    "waMessageId": "3EB0C767D26A1D8E2B5F",
    "mediaUrl": "https://...&X-Amz-Expires=86400",
    "mimeType": "image/jpeg"
  }
}

Campos de data:

O campo type em detalhe

O type indica como interpretar o restante do payload:

O campo from: dois (e às vezes três) formatos

O from identifica a origem e não é sempre um telefone. Ele pode vir em três formatos, distinguíveis pelo sufixo após o @:

• Número com sufixo @s.whatsapp.net — por exemplo 5511999999999@s.whatsapp.net. É o caso mais comum: o trecho antes do @ é o telefone em E.164 (sem o +).
• LID com sufixo @lid — por exemplo 123456789@lid. Ocorre quando o contato usa o recurso de privacidade do WhatsApp e o número real ainda não foi resolvido. Aqui o valor antes do @lid é um identificador interno, não um telefone.
• Grupo com sufixo @g.us — por exemplo 120363012345678901@g.us. Aparece quando a mensagem foi recebida em um grupo. O valor antes do @ identifica o grupo, não uma pessoa.

Mídia: como baixar o arquivo

Em mensagens de mídia, o binário não vem no payload — vem uma URL pré-assinada em mediaUrl, com validade de 24 horas.

"data": {
  "from": "5511999999999@s.whatsapp.net",
  "type": "audio",
  "text": "",
  "waMessageId": "3EB0C767D26A1D8E2B5F",
  "mediaUrl": "https://....s3.amazonaws.com/media/...&X-Amz-Expires=86400",
  "mimeType": "audio/ogg"
}

Baixe o arquivo diretamente pela URL, com um GET simples e sem credenciais adicionais (a autorização já está embutida na própria URL):

curl -L -o arquivo "$MEDIA_URL"

O que não gera message.received

Apenas mensagens com conteúdo exibível geram o evento. Não são entregues:

• Ecos das próprias mensagens que a instância envia (mensagens "de mim").
• Mensagens de controle do WhatsApp: cabeçalho de álbum (vem junto das fotos), reações, edições, exclusões, distribuição de chave de sessão e mensagens de protocolo.
• Status (status@broadcast), listas de transmissão e canais (newsletters) — não são conversas e não viram evento.
• Grupos, quando a configuração ignoreGroups da instância está ligada.

message.status

Disparado quando muda o status de entrega de uma mensagem que a instância enviou. Como o envio é assíncrono (a API responde 202 apenas enfileirando a mensagem), este evento é a sua confirmação de entrega e de leitura.

{
  "event": "message.status",
  "instanceId": "cm5x8a9k20001abc123def456",
  "timestamp": "2026-05-29T22:17:00Z",
  "data": {
    "status": "READ",
    "to": "5511999999999@s.whatsapp.net",
    "waMessageIds": ["3EB0C767D26A1D8E2B5F", "3EB1A2B3C4D5E6F70819"]
  }
}

Campos de data:

Para correlacionar com o que você enviou, guarde o waMessageId retornado no envio e cruze-o com os waMessageIds recebidos aqui.

instance.status

Disparado quando muda o status de conexão da instância com o WhatsApp.

{
  "event": "instance.status",
  "instanceId": "cm5x8a9k20001abc123def456",
  "timestamp": "2026-05-29T22:18:00Z",
  "data": {
    "status": "DISCONNECTED",
    "jid": "",
    "reason": ""
  }
}

Campos de data:

Valores possíveis de status:

call.received

Disparado quando a instância recebe uma chamada (voz ou vídeo) de um contato — no mesmo instante em que o telefone "tocaria". Útil para registrar tentativas de ligação, alertar um atendente, ou casar com a configuração de rejeitar chamadas: mesmo com a rejeição ligada, o call.received é emitido — a chamada chegou, e só depois foi rejeitada.

{
  "event": "call.received",
  "instanceId": "inst_123",
  "timestamp": "2026-06-06T12:00:00Z",
  "data": {
    "from": "5511999999999@s.whatsapp.net",
    "callId": "AB12CD34EF56"
  }
}

message.deleted

Disparado quando um contato apaga para todos (revoga) uma mensagem em uma conversa com a instância — o "Apagar mensagem → Apagar para todos" do WhatsApp. Serve para manter o seu CRM/registro fiel: ao receber este evento, marque como apagada (ou esconda) a mensagem correspondente no seu sistema.

{
  "event": "message.deleted",
  "instanceId": "inst_123",
  "timestamp": "2026-06-06T12:00:00Z",
  "data": {
    "from": "5511999999999@s.whatsapp.net",
    "waMessageId": "3EB0C767D26A1D8E2B5F"
  }
}

group.participants

Disparado quando a composição de um grupo muda: alguém entrou, saiu (ou foi removido), foi promovido a admin ou rebaixado. Só vale para grupos dos quais a instância participa.

{
  "event": "group.participants",
  "instanceId": "inst_123",
  "timestamp": "2026-06-06T12:00:00Z",
  "data": {
    "groupJid": "120363012345678901@g.us",
    "by": "5511999999999@s.whatsapp.net",
    "joined": ["5511888888888@s.whatsapp.net"],
    "left": [],
    "promoted": [],
    "demoted": []
  }
}

group.updated

Disparado quando os metadados de um grupo mudam — o nome ou o tópico (descrição).

{
  "event": "group.updated",
  "instanceId": "inst_123",
  "timestamp": "2026-06-06T12:00:00Z",
  "data": {
    "groupJid": "120363012345678901@g.us",
    "by": "5511999999999@s.whatsapp.net",
    "name": "Novo nome do grupo"
  }
}

contact.updated

Disparado quando o nome de exibição (push name) de um contato muda — percebido ao receber uma mensagem dele com um nome diferente do que estava em cache.

{
  "event": "contact.updated",
  "instanceId": "inst_123",
  "timestamp": "2026-06-06T12:00:00Z",
  "data": {
    "from": "5511999999999@s.whatsapp.net",
    "oldName": "João",
    "newName": "João Silva"
  }
}

label.updated

Disparado quando uma etiqueta (recurso do WhatsApp Business) é criada, renomeada ou apagada.

{
  "event": "label.updated",
  "instanceId": "inst_123",
  "timestamp": "2026-06-06T12:00:00Z",
  "data": {
    "labelId": "5",
    "name": "Cliente VIP",
    "color": 3,
    "deleted": false
  }
}

label.association

Disparado quando uma etiqueta é aplicada ou removida de uma conversa.

{
  "event": "label.association",
  "instanceId": "inst_123",
  "timestamp": "2026-06-06T12:00:00Z",
  "data": {
    "labelId": "5",
    "chat": "5511999999999@s.whatsapp.net",
    "labeled": true
  }
}

campaign.status

Disparado a cada mudança de status de um destinatário de uma campanha de disparo em massa. É o acompanhamento em tempo real do disparo, por destinatário — complementar ao agregado de GET /v1/campaigns/{id}.

{
  "event": "campaign.status",
  "instanceId": "cm5x8a9k20001abc123def456",
  "timestamp": "2026-06-18T14:32:00Z",
  "data": {
    "campaignId": "camp_3Hk9Zq2pVxL",
    "recipient": "5511999999999",
    "name": "Maria",
    "status": "delivered",
    "error": null
  }
}

Campos de data:

O ciclo típico de um destinatário é sent -> delivered -> read, e responded se o contato responder. invalid sai antes do envio (número sem WhatsApp, quando validateNumbers está ligado) e não consome o teto diário; failed é uma falha real de envio. Trate cada evento como uma atualização idempotente do estado daquele destinatário — nem todos os estados ocorrem para todos, e a ordem pode variar.

Erros e situações de borda

Estes eventos são entregues ao seu endpoint; eles não retornam códigos de erro para você. O que você precisa observar do lado do receptor:

• Responda 2xx rápido. Qualquer resposta fora de 2xx, timeout (15s) ou erro de rede faz a entrega falhar e ser reenviada com backoff, até 6 tentativas. Ver Entrega e retry.
• Deduplique. Por causa do retry, o mesmo evento pode chegar mais de uma vez. Use um identificador de negócio em data — waMessageId em message.received, waMessageIds em message.status — como chave de idempotência. O X-Pepino-Webhook-Id é constante por webhook e não serve para isso.
• Valide a assinatura. Trate como inválida (e descarte) qualquer entrega cujo X-Pepino-Signature não bata com o HMAC do corpo bruto. Ver Assinatura.
• Tolere campos ausentes e tipos novos. Em message.received, mediaUrl/mimeType podem não vir; text pode ser "". Em instance.status, jid/reason podem ser "". Trate type e status como listas abertas, com um caso default.

Os erros de cadastro de webhook (criar/listar/remover via POST /v1/webhooks) — como 400 para evento inválido ou URL recusada, 401 para key ausente/inválida — estão documentados em Webhooks.

Próximos passos

• Webhooks — como cadastrar webhooks via API e gerenciar o secret.
• Assinatura — como validar X-Pepino-Signature (com exemplos em Node, Python e Go).
• Entrega e retry — timeout, critério de sucesso e política de reenvio.
• WebSocket — receber os mesmos eventos em tempo real, sem endpoint público.