Toda mensagem recebida, mudança de status de entrega, conexão ou desconexão de instância gera um evento na GoZAP. Dois mecanismos estão disponíveis para consumir esses eventos: Webhooks (HTTP POST para seu servidor) e SSE — Server-Sent Events (stream persistente para o browser). Cada um tem seu lugar certo.
Webhooks são ideais para backends que precisam reagir a eventos e executar lógica de negócio. SSE serve para dashboards e interfaces que precisam exibir atualizações em tempo real sem polling. Use os dois juntos para ter o melhor dos dois mundos.
"Um webhook sem validação de assinatura é uma porta aberta. Valide o HMAC — sempre."
Configurando e consumindo
01
Configurando webhook com assinatura HMAC
Todo webhook da GoZAP é assinado com HMAC-SHA256 usando o secret configurado na instância. Seu endpoint deve validar a assinatura antes de processar o payload — eventos não validados devem ser descartados com HTTP 401.
Validação HMAC — Node.js
// Middleware de validação de assinatura GoZAPconst crypto = require('crypto');functionvalidateGoZAPSignature(req, res, next) {const sig = req.headers['x-gozap-signature'];const secret = process.env.GOZAP_WEBHOOK_SECRET;const body = JSON.stringify(req.body);const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(body) .digest('hex');if (!crypto.timingSafeEqual( Buffer.from(sig), Buffer.from(expected) )) return res.status(401).send('Unauthorized'); next();}─────────────────────────────────────────────────────✔ timingSafeEqual — imune a timing attacks
Eventos disponíveis via webhook
message.received — nova mensagem recebida
message.status — entregue, lido, falha
session.status — conectado, desconectado
group.update — participantes, nome, foto alterados
02
Processamento idempotente — evitando duplicatas
A GoZAP entrega eventos com garantia at-least-once — em caso de timeout no seu endpoint, o evento pode ser reenviado. Cada evento tem um campo eventId único. Armazene os IDs processados (Redis ou banco) e rejeite duplicatas antes de processar.
Deduplicação com Redis
// Verificar e marcar evento como processadoasync functionprocessWebhook(event) {const key = `webhook:processed:${event.eventId}`;// SET NX — só define se não existir (idempotente)const isNew = await redis.set(key, '1', { NX: true, EX: 86400// TTL: 24h });if (!isNew) { console.log('Evento duplicado ignorado:', event.eventId);return; // retorna 200 mesmo assim }await handleEvent(event); // processar}─────────────────────────────────────────────────────✔ Sempre retornar HTTP 200 — mesmo em duplicata
03
SSE — stream de eventos para o browser
Server-Sent Events (SSE) é ideal para dashboards e painéis de monitoramento. A GoZAP expõe um endpoint SSE por instância — abra a conexão uma vez e receba todos os eventos como um stream de texto, sem polling. Reconexão automática é gerenciada pelo browser.
Consumindo SSE — JavaScript
// Conectar ao stream SSE da instânciaconst sse = new EventSource(`https://api.gozap.dev/instance/minha-instancia/events`, { headers: { Authorization: `Bearer ${API_KEY}` } });sse.addEventListener('message.received', (e) => {const msg = JSON.parse(e.data); console.log('Nova mensagem:', msg.from, msg.body); renderMessage(msg); // atualizar UI});sse.addEventListener('session.status', (e) => { updateStatusIndicator(JSON.parse(e.data).status);});─────────────────────────────────────────────────────✔ Reconexão automática após queda de conexão
04
Monitorando falhas de entrega de webhook
A GoZAP registra todas as tentativas de entrega de webhook no painel. Se o seu endpoint retornar erro por 3 tentativas consecutivas, a instância é marcada com alerta e você recebe notificação. Consulte o log de entregas via API para investigar falhas.
GET /api/instance/webhook/logs
{"logs": [ {"eventId": "evt_abc123","event": "message.received","attempts": 3,"lastStatus": 503,"lastAttemptAt": "2026-08-29T15:02:11Z","nextRetryAt": "2026-08-29T15:07:11Z" } ]}─────────────────────────────────────────────────────✔ Retry automático com backoff exponencial✔ Alerta após 3 falhas consecutivas
Checklist de produção para webhooks
Endpoint responde em menos de 5s — processe assíncrono
Validar assinatura HMAC antes de qualquer processamento
Deduplicação por eventId obrigatória em produção
Log de todos os eventos recebidos — facilita debug
Documentação completa
Referência completa de Webhooks e SSE na GoZAP
A documentação GoZAP inclui lista de todos os eventos, schema de cada payload, exemplos de validação de assinatura em Node.js, Python e PHP, e guia de troubleshooting de entregas.