Skip to main content
Webhooks permitem que sua aplicação receba notificações em tempo real quando eventos acontecem no Pagozz, como um pagamento confirmado ou um link criado.

​
Como funciona

Evento no Pagozz (pagamento confirmado, link criado, etc.)
  → Pagozz assina payload com HMAC-SHA256
  → POST para a URL do seu endpoint
  → Sucesso (2xx) → delivered
  → Falha → retry automático com backoff exponencial

​
Eventos disponíveis

EventoDescrição
payment.createdPagamento criado e aguardando
payment.succeededPagamento confirmado
payment.failedPagamento falhou
payment.expiredPagamento expirou
link.createdNovo link de pagamento criado
link.updatedLink de pagamento atualizado
link.deactivatedLink de pagamento desativado
payout.createdSaque solicitado
payout.succeededSaque concluído
payout.failedSaque falhou

​
Payload

Todos os webhooks seguem o mesmo formato: 
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "type": "payment.succeeded",
  "version": "2026-03-15",
  "when": "2026-02-27T14:30:00.000Z",
  "environment": "live",
  "data": {
    "transaction_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "amount": 15000,
    "status": "paid",
    "payment_method": "pix",
    "completed_at": "2026-02-27T14:30:00.000Z"
  }
}
CampoTipoDescrição
idstringID da delivery (UUID). Use para idempotência
typestringTipo do evento
versionstringVersão da API usada
whenstringISO 8601 timestamp do evento
environmenttest | liveAmbiente do evento
dataobjectDados do recurso relacionado

​
Headers

Cada request de webhook inclui:
HeaderDescrição
Content-Typeapplication/json
X-Pagozz-EventTipo do evento
X-Pagozz-DeliveryID único da delivery
X-Pagozz-TimestampUnix timestamp da assinatura
X-Pagozz-SignatureAssinatura HMAC-SHA256
User-AgentPagozz-Webhook/1.0

​
Verificação de assinatura

Sempre verifique a assinatura para garantir que o webhook veio do Pagozz.

​
Algoritmo

  1. Extrair X-Pagozz-Timestamp e X-Pagozz-Signature dos headers
  2. Montar o conteúdo assinado: {timestamp}.{body}
  3. Calcular HMAC-SHA256 com seu secret
  4. Comparar com a assinatura recebida (constant-time)
  5. Verificar que o timestamp está dentro de 5 minutos
import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhook(secret, signature, timestamp, body) {
  // Verificar tolerância de tempo (5 min)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 300) return false;

  // Calcular assinatura esperada
  const signedContent = `${timestamp}.${body}`;
  const expected = createHmac('sha256', secret)
    .update(signedContent)
    .digest('hex');

  // Comparação constant-time
  return timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

​
Retentativas

Quando seu endpoint retorna status diferente de 2xx (ou timeout), o Pagozz retenta automaticamente:
TentativaDelayTempo acumulado
1imediato0
21 minuto1 min
35 minutos6 min
430 minutos36 min
52 horas~2.5h
68 horas~10.5h
724 horas~34.5h
848 horas~82.5h (~3.4 dias)
Após 8 tentativas sem sucesso, a delivery é marcada como exhausted e um email de alerta é enviado.

​
Boas práticas

Responda rápido

Retorne 2xx em até 10 segundos (timeout do Pagozz).

Idempotência

Use o id do evento para evitar processar duplicatas.

Processe async

Receba o webhook, retorne 200, e processe em background.

Verifique assinatura

Sempre valide antes de processar qualquer evento.

​
Limites

LimiteValor
Timeout por request10 segundos
Tentativas por delivery8
Janela total de retentativas~3.4 dias
Tolerância de timestamp5 minutos