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": "..." } }

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
{ "wa_id": "...", "category": "...", "value": "stop|resume", "detail": "..." }

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.