Webhooks — eventos

Catálogo de eventos, envelope de entrega, verificação de assinatura HMAC e política de retry.

Envelope de entrega

Toda entrega é um POST application/json com este envelope:

{
  "id": "evt_...",
  "type": "message.delivered",
  "api_version": "2026-06-01",
  "created_at": "2026-06-22T14:05:00.000Z",
  "account_id": "1029384756",
  "data": { }
}

Catálogo de eventos + payloads

Mensagens

// message.sent | message.delivered | message.read
{ "message_id": "...", "to": "...", "status": "sent|delivered|read", "pricing": { } }

// message.failed
{ "message_id": "...", "to": "...", "status": "failed", "errors": [ ] }

// message.received
{ "message_id": "...", "from": "...", "contact_name": "...", "type": "text",
  "text": "...", "media": { "id": "...", "mime_type": "...", "caption": "..." } }

// message.echoed
{ "message_id": "...", "from": "...", "to": "...", "type": "text",
  "text": "...", "media": { "id": "...", "mime_type": "...", "caption": "..." } }

Resposta a botão e lista

Não existe evento separado para clique em botão. O WhatsApp entrega a escolha do contato como uma mensagem inbound normal — ou seja, chega em message.received, com type diferente de text. Basta assinar message.received.

// clique em botão de resposta rápida enviado pela API
{ "message_id": "wamid...", "from": "5575...", "contact_name": "Pedro", "type": "interactive",
  "interactive": { "type": "button_reply", "reply": { "id": "fruta_caju", "title": "Caju" } },
  "context": { "message_id": "wamid... (mensagem que levou os botões)", "from": "5511..." } }

// escolha em lista de opções
{ "message_id": "wamid...", "from": "5575...", "type": "interactive",
  "interactive": { "type": "list_reply",
                   "reply": { "id": "h_0800", "title": "08:00", "description": "Dr. Italo Pinto" } },
  "context": { "message_id": "wamid...", "from": "5511..." } }

// quick-reply de template (campanha)
{ "message_id": "wamid...", "from": "5575...", "type": "button",
  "button": { "text": "Quero saber mais", "payload": "PROMO_2026" },
  "context": { "message_id": "wamid... (a mensagem da campanha)", "from": "5511..." } }

• interactive.reply.id é o id que você definiu no envio — use ele para rotear a automação (title é o texto exibido e pode mudar).
• context.message_id é o message_id da mensagem que levou os botões. É a única forma de correlacionar o clique com o disparo que o originou. Aparece em qualquer message.received que seja resposta a uma mensagem sua (inclusive texto citado); quando não há resposta a nada, a chave é omitida.
• Tipos interativos sem forma estável (ex.: nfm_reply de Flows) trazem apenas interactive.type.

Templates

// template.status_updated
{ "template_name": "...", "language": "...", "event": "APPROVED", "reason": null }

// template.quality_updated
{ "template_name": "...", "language": "...", "previous_quality_score": "...", "new_quality_score": "..." }

Número de telefone

// phone_number.quality_updated
{ "display_phone_number": "...", "event": "...", "current_limit": "..." }

// phone_number.name_updated
{ "display_phone_number": "...", "decision": "...", "requested_verified_name": "...", "rejection_reason": "..." }

Conta / capacidade

// account.updated
{ "event": "...", "account_review_status": "...", "business_verification_status": "...", "restriction_info": [ ] }

// account.alert
{ "entity_type": "...", "entity_id": "...", "alert_severity": "...", "alert_status": "...", "alert_type": "...", "alert_description": "..." }

// business_capability.updated
{ "max_daily_conversation_per_phone": "...", "max_phone_numbers_per_business": "...", "max_phone_numbers_per_waba": "..." }

Contato / usuário

// contact.synced
{ "action": "add|remove", "name": "...", "phone": "..." }

// user.preferences_updated — opt-out/opt-in nativo
{ "wa_id": "...", "category": "...", "value": "stop|resume", "detail": "..." }

// user.preferences_updated — aceite de In-App Signup
{ "wa_id": "...", "category": "marketing_messages", "value": "signup", "detail": "...", "signup_id": "...", "user_id": "..." }

signup_id é o id retornado por POST /v1/accounts/{id}/signups (ver In-App Signup) — use pra saber qual link/campanha o contato usou (se você criou vários).

Onboarding de parceiros

// account.connected
{ "external_ref": "cliente-42", "waba_id": "1234567890", "phone_number": "+5511999999999",
  "display_name": "Padaria do Zé", "onboarded_via": "PARTNER" }

• external_ref é o identificador que você enviou em POST /v1/onboarding/sessions — use-o para casar o evento com o seu cliente.
• O account_id do envelope é o id da conexão criada: o mesmo de GET /v1/accounts e o que você passa ao enviar mensagens.
• O payload é curado: nunca contém token de acesso.

Assinatura (verificação)

Segue o padrão Standard Webhooks. Cada entrega traz 3 headers:

Segredo: whsec_ + 24 bytes aleatórios em base64.

Algoritmo de assinatura

1. secretBytes = base64decode(secret.slice(7)) (remove o prefixo whsec_).
2. signedContent = "{webhook-id}.{webhook-timestamp}.{raw_body}".
3. signature = base64(HMAC_SHA256(secretBytes, signedContent)).
4. Header = v1,{signature}.

Para verificar (no seu servidor)

1. Extraia os 3 headers.
2. Confirme que webhook-timestamp está dentro de ~5 min do agora (anti-replay).
3. Recomponha signedContent com o corpo bruto recebido (bytes exatos, antes de qualquer JSON.parse).
4. Recalcule o HMAC e compare (constante) com a parte após v1,.
5. Aceite se bater; rejeite se não.

Exemplo (Node.js)

# Não há exemplo cURL para verificação — rode dentro do seu app.

import crypto from 'crypto'

function verify(secret, headers, rawBody) {
const id = headers['webhook-id']
const ts = headers['webhook-timestamp']
const sig = headers['webhook-signature'] // "v1,xxxx"
const secretBytes = Buffer.from(secret.slice(7), 'base64') // tira "whsec_"
const signed = id + '.' + ts + '.' + rawBody
const expected = 'v1,' + crypto.createHmac('sha256', secretBytes).update(signed).digest('base64')
// comparação em tempo constante
if (sig.length !== expected.length) return false
return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}

import hmac, hashlib, base64, time

def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
  wh_id = headers['webhook-id']
  ts = headers['webhook-timestamp']
  sig = headers['webhook-signature']  # "v1,xxxx"
  secret_bytes = base64.b64decode(secret[7:])  # tira "whsec_"
  signed = f"{wh_id}.{ts}.".encode() + raw_body
  expected = 'v1,' + base64.b64encode(
      hmac.new(secret_bytes, signed, hashlib.sha256).digest()
  ).decode()
  # anti-replay: rejeita timestamps fora de 5 min
  if abs(int(ts) - int(time.time())) > 300:
      return False
  return hmac.compare_digest(sig, expected)

<?php
function verify(string $secret, array $headers, string $rawBody): bool {
$id  = $headers['webhook-id'];
$ts  = $headers['webhook-timestamp'];
$sig = $headers['webhook-signature']; // "v1,xxxx"
$secretBytes = base64_decode(substr($secret, 7)); // tira "whsec_"
$signed = $id . '.' . $ts . '.' . $rawBody;
$expected = 'v1,' . base64_encode(hash_hmac('sha256', $signed, $secretBytes, true));
// anti-replay
if (abs(time() - (int)$ts) > 300) return false;
return hash_equals($expected, $sig);
}

Política de retry / entrega

Cronograma de retry após falha: 5s → 5min → 30min → 2h → 5h → 10h → 14h → DEAD (≈ 36h no total).

Estados de delivery: PENDING → DELIVERING → SUCCESS | FAILED (re-tentará) | DEAD (terminal).

Campos de uma delivery (via API): id, event_type, status, attempts (0–8), last_response_code, last_error, delivered_at, created_at.