Webhooks

16. 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 e message.played, o BiaZap 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.

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

Resposta 200: Objeto webhook sem o campo secret.

PATCH/v1/webhooks/{webhookId}#

Atualiza um webhook.

Auth: Owner, Admin

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

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

Query Parameters:

Resposta 200:

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

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

Reenvia um evento que falhou.

Auth: Owner, Admin 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 BiaZap 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 BiaZap 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-BiaZap-Timestamp e X-BiaZap-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 BiaZap:

Content-Type: application/json
User-Agent: BiaZap-Webhook/1.0
X-BiaZap-Timestamp: 1711035600
X-BiaZap-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 BiaZap 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).

Eventos exclusivos do canal oficial#

Além de todos os eventos de mensagem abaixo, o canal oficial emite:

message.interactive_reply_received — o contato tocou em um botão ou item de lista de um template/mensagem interativa. Traz a seleção estruturada para automação, além de um message.received com o texto do botão como conteúdo.

{
  "chat": "554199990000@s.whatsapp.net",
  "phone": "554199990000",
  "sender": "554199990000@s.whatsapp.net",
  "reply_type": "button_reply",
  "selected_id": "TRACK_ORDER",
  "selected_display_text": "Acompanhar pedido",
  "title": "",
  "description": "",
  "timestamp": 1784340265
}

reply_type é button_reply, list_reply ou nfm (resposta de um Flow). Para list_reply, title e description trazem o item escolhido. Para nfm, o payload traz native_flow_name + native_flow_params_json (o JSON do formulário submetido pelo contato).

official.template_status — a Meta mudou o status de aprovação de um template (PENDING → APPROVED / REJECTED).

{ "template_name": "confirmacao_pedido", "language": "pt_BR", "status": "APPROVED", "reason": "" }

official.quality_update — mudou o quality rating do número ou o tier de limite de mensagens.

{ "display_phone_number": "+55 41 6349-0888", "quality_rating": "GREEN", "messaging_limit_tier": "TIER_1K" }

official.reauth_required — o token da WABA expirou ou foi revogado. A conexão fica DISCONNECTED até você reconectar (Embedded Signup ou token novo).

{ "instance_id": "84c2e480-...", "reason": "token expired or revoked" }

Status de entrega das mensagens que você envia (message.sent, message.delivered, message.read, message.delivery_failed) chegam normalmente pelos eventos abaixo, com o message_id (UUID Catcher) para correlação.

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}. Ecos das mensagens que você mesmo enviou não geram esse evento.

{
  "phone": "554192464230",
  "from": "554192464230@s.whatsapp.net",
  "chat": "554192464230@s.whatsapp.net",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "whatsapp_message_ids": ["3EB0ABC123DEF456"],
  "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,
  "push_name": "Joao Silva"
}

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"
  },
  "is_forwarded": false,
  "timestamp": 1741360245,
  "push_name": "Patricia"
}

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

ad_context sem URL Meta: quando a mensagem veio de um anúncio Click-to-WhatsApp (Instagram/Facebook), ela carrega ad_context (source_type, source_id, title, body, media_type, ctwa_clid) com apenas texto e tracking. As URLs de mídia do anúncio e o permalink do post são intencionalmente removidos — a Catcher nunca expõe uma URL de CDN da Meta. Use title/body para o conteúdo e ctwa_clid/ref para atribuição de campanha.

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",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "whatsapp_message_ids": ["3EB0DEF456ABC123"],
  "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
}

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 BiaZap 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.

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",
  "whatsapp_message_ids": ["3EB0DEF456ABC123", "3EB0DEF456ABC124"],
  "status": "delivered",
  "timestamp": 1741360310
}

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",
  "whatsapp_message_ids": ["3EB0DEF456ABC123"],
  "status": "read",
  "timestamp": 1741360350
}

message.played#

Disparado quando o contato ouve pela primeira vez um áudio (voice note) que você enviou. Atualiza status=played e played_at na tabela messages. É a prova de que a mídia foi consumida (o salto delivered → played).

{
  "phone": "554192464230",
  "message_ids": ["550e8400-e29b-41d4-a716-446655440001"],
  "chat": "554192464230@s.whatsapp.net",
  "status": "played",
  "timestamp": 1741360400
}

connection.update#

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

{
  "status": "connected",
  "reason": "",
  "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

contact.update#

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

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

Ações possíveis:

Avatar cache: Quando action e picture_change, a BiaZap 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.
• 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 para garantir visibilidade em code review.

Payloads adicionais de eventos#

Os eventos abaixo também fazem parte do conjunto de eventos. Os exemplos usam o envelope real {type,data}.

instance.deleted#

Campos: instance_id, phone, timestamp.

{ "type": "instance.deleted", "data": { "instance_id": "84c2e480-...", "phone": "554137984905", "timestamp": 1741361650 } }

message.reaction_received#

Campos: chat, phone, sender, envelope_whatsapp_message_id, target_whatsapp_message_id, target_from_me, emoji, timestamp.

{ "type": "message.reaction_received", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "sender": "554137984905@s.whatsapp.net", "envelope_whatsapp_message_id": "3EB0REACTION", "target_whatsapp_message_id": "3EB0TARGET", "target_from_me": true, "emoji": "👍", "timestamp": 1741361650 } }

message.delivery_failed#

Campos: chat, phone, message_id, whatsapp_message_id, idempotency_key, task_id, message_type, reason, last_error, attempt_count, timestamp.

{ "type": "message.delivery_failed", "data": { "chat": "554137984905@s.whatsapp.net", "phone": "554137984905", "message_id": "550e8400-e29b-41d4-a716-446655440000", "idempotency_key": "send-001", "task_id": "asynq:task:abc", "message_type": "text", "reason": "retry_exhausted", "last_error": "timeout", "attempt_count": 5, "timestamp": 1741361650 } }

contact.temperature_changed#

Campos: remote_jid, phone, old_tier, new_tier, old_score, new_score, direction, trigger, timestamp.

{ "type": "contact.temperature_changed", "data": { "remote_jid": "554137984905@s.whatsapp.net", "phone": "554137984905", "old_tier": "cold", "new_tier": "warm", "old_score": 25, "new_score": 42, "direction": "inbound", "trigger": "message.received", "timestamp": 1741361650 } }

anti_spam.blocked#

Campos: remote_jid, phone, rule, detail, message_type, bypass_available, bypass_quota_left, content_hash, timestamp.

{ "type": "anti_spam.blocked", "data": { "remote_jid": "554137984905@s.whatsapp.net", "phone": "554137984905", "rule": "duplicate_content", "detail": "same content sent in rolling 24h", "message_type": "text", "bypass_available": true, "bypass_quota_left": 2, "content_hash": "sha256:abc", "timestamp": 1741361650 } }

whatsapp.policy_warning#

Campos: warning_code, category, message, expires_at, severity_hint, recommended_action, timestamp.

{ "type": "whatsapp.policy_warning", "data": { "warning_code": "rate_limit", "category": "anti_abuse", "message": "rate limit warning", "expires_at": "2026-05-21T13:00:00Z", "severity_hint": "warn", "recommended_action": "slow_down", "timestamp": 1741361650 } }

message.order_received#

Campos: chat, phone, sender, order_id, item_count, total_amount_1000, currency, timestamp. Evento operacional (não cria linha) — o contato fez um pedido do catálogo (commerce). total_amount_1000 é o valor total em milésimos da moeda (ex.: 45990 = 45,99 BRL).

{ "type": "message.order_received", "data": { "chat": "554199990000@s.whatsapp.net", "phone": "554199990000", "sender": "554199990000@s.whatsapp.net", "order_id": "SMB123456", "item_count": 3, "total_amount_1000": 45990, "currency": "BRL", "timestamp": 1741361650 } }

contact.identity_changed#

Campos: phone, jid, timestamp. O contato trocou de número de telefone (system message customer_changed_number). Use para reconciliar o contato com o novo jid.

{ "type": "contact.identity_changed", "data": { "phone": "554199991111", "jid": "554199991111@s.whatsapp.net", "timestamp": 1741361650 } }

call.received#

Campos: phone, from, call_id, state, timestamp. Chamada de voz recebida (Calling API, evento connect). Persistida em call_logs. O SDP offer nunca é exposto no payload — só o sinal.

{ "type": "call.received", "data": { "phone": "554199990000", "from": "554199990000@s.whatsapp.net", "call_id": "wacid.ABCD1234", "state": "ringing", "timestamp": 1741361650 } }

call.ended#

Campos: phone, from, call_id, reason, duration, timestamp. Chamada de voz encerrada (evento terminate). duration em segundos (0 se não foi atendida).

{ "type": "call.ended", "data": { "phone": "554199990000", "from": "554199990000@s.whatsapp.net", "call_id": "wacid.ABCD1234", "reason": "completed", "duration": 42, "timestamp": 1741361650 } }

official.marketing_optout#

Campos: phone, from, category, opted_out, value, timestamp. O contato mudou a preferência de marketing (webhook user_preferences). value é stop (opt-out, opted_out=true) ou resume (opt-in de volta, opted_out=false). Envios de template category:"marketing" para um contato com opted_out=true são bloqueados com 409 BLOCKED_MARKETING_OPTOUT.

{ "type": "official.marketing_optout", "data": { "phone": "554199990000", "from": "554199990000@s.whatsapp.net", "category": "marketing_messages", "opted_out": true, "value": "stop", "timestamp": 1741361650 } }

Eventos de observabilidade da conta (official.*)#

Oito eventos de saúde da conta/número/template usam o payload genérico { field, detail, timestamp }, onde field é o campo bruto do webhook da Meta e detail traz o valor decodificado. Todos carregam apenas estado da conta, nunca mídia/URL — use para dashboards de saúde da WABA e alertas operacionais.

{ "type": "official.template_quality", "data": { "field": "message_template_quality_update", "detail": { "message_template_name": "confirmacao_pedido", "message_template_language": "pt_BR", "new_quality_score": "GREEN" }, "timestamp": 1741361650 } }

Persistencia de eventos#

Eventos são persistidos no histórico operacional do tenant quando passam pelo pipeline de realtime/webhooks. Eventos operacionais (connection.update, contact.update, official.template_status, official.quality_update, contact.temperature_changed, whatsapp.policy_warning) não criam/alteram linhas em messages — são entregues via webhook/SSE/WebSocket e consultáveis pelo histórico de eventos quando habilitado.

Ciclo de vida da mensagem na tabela messages:

queued → sent → delivered → read

Tabelas de eventos: