Eventos assinados e entregues com segurança.

Eventos disponíveis

• instance.status — conexão mudou de estado.
• campaign.started — execução iniciada.
• campaign.completed — execução encerrada com totais.
• delivery.sent — destino processado com sucesso.
• delivery.failed — falha definitiva ou revisão necessária.
• contact.received — contato elegível recebido.

Validar a assinatura

Cada POST contém X-WZAP-Event, X-WZAP-Event-Id, X-WZAP-Timestamp e X-WZAP-Signature. Calcule HMAC-SHA256 sobre timestamp + "." + corpo_original usando o segredo exibido na criação.

$timestamp = $_SERVER['HTTP_X_WZAP_TIMESTAMP'] ?? '';
$provided = $_SERVER['HTTP_X_WZAP_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');

if (abs(time() - (int)$timestamp) > 300) { http_response_code(401); exit; }
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $provided)) { http_response_code(401); exit; }

Armazene o event_id com índice único antes de aplicar o evento. Assim uma repetição continua idempotente.

Payload

{
  "event_id": "uuid",
  "type": "campaign.completed",
  "occurred_at": "2026-07-22T21:00:00Z",
  "data": {
    "campaign_id": "uuid",
    "sent": 148,
    "failed": 2
  }
}

O objeto data é específico do evento e sanitizado. Tokens de conexão, credenciais e detalhes do motor não fazem parte do contrato.

Entrega e retentativas

Responda com qualquer status 2xx rapidamente. Timeout ou resposta não-2xx gera até oito tentativas com backoff. Processe em fila própria quando sua regra levar mais tempo.

Segredo e rotação

O segredo aparece uma única vez. Ao rotacionar, novas entregas passam imediatamente a usar o novo segredo. Para troca sem interrupção, aceite temporariamente o segredo anterior e o novo no seu receptor, rotacione no painel, atualize seu cofre e remova o anterior.