Como consumir webhooks e eventos SSE da GoZAP

Como consumir eventos da GoZAP?

Webhooks enviam requisições POST com JSON para destinos cadastrados. SSE mantém uma conexão aberta e transmite eventos disponíveis enquanto o cliente está conectado.

“Use webhooks para entregas persistentes e considere SSE uma transmissão ao vivo, sujeita a perda.”

Como configurar um webhook?

Consulte e atualize a lista de webhooks da instância. A API também permite consultar os erros registrados para essas entregas.

Quando a requisição é assinada?

A assinatura HMAC não é aplicada automaticamente a todos os webhooks. O modo de segurança pode ser none ou hmac_sha256. Quando HMAC está habilitado, a requisição inclui X-GoZap-Signature e X-GoZap-Timestamp; a assinatura usa o timestamp, um ponto e o payload original. A composição assinada é:

timestamp + "." + payload_original

Como funciona o stream SSE?

A API disponibiliza GET /sse com autenticação compatível com a instância ou com o widget de chamadas. O hub mantém um buffer de 32 eventos por assinante; se ele encher, os eventos seguintes são descartados. O servidor não oferece replay por Last-Event-ID.

Webhooks e SSE têm a mesma garantia de entrega?

Não. O código do hub SSE o define como best-effort. A fila de webhooks mantém tentativas configuradas e registra erros, mas não declara uma garantia universal at-least-once nem um eventId comum a todos os eventos. Se seu processamento precisar tolerar repetição, escolha uma chave idempotente baseada nos campos estáveis do evento recebido.