Webhooks

Configure webhooks para receber notificações em tempo real quando cobranças forem pagas, expiradas ou atualizadas.

Como funciona

Configure a URL de webhook no dashboard ou via API
Quando um evento ocorre, enviamos um POST para sua URL
O payload é assinado com HMAC-SHA256 usando seu secret
Se a entrega falhar, fazemos até 5 tentativas com backoff exponencial

Payload de exemplo

POST na sua URLJSON

{
  "event": "charge.paid",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "txid": "pagniv_abc123def456",
    "amount": 150.00,
    "status": "PAID",
    "paidAt": "2026-01-15T11:05:00Z"
  },
  "timestamp": "2026-01-15T11:05:01Z"
}

Verificando a assinatura

Node.jsjavascript

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// No seu endpoint:
const signature = req.headers['x-webhook-signature'];
const isValid = verifyWebhook(req.body, signature, 'seu_secret');

Configurar webhook

POST

/v1/webhook-config

Auth

Cria ou atualiza a configuração de webhook do merchant.

Body (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL HTTPS que receberá os webhooks
`secret`	string	Não	Secret para assinatura HMAC (mín. 16 caracteres). Se omitido, um é gerado automaticamente.

Exemplobash

curl -X POST https://api.pagniv.com/v1/webhook-config \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meu-site.com/webhooks/pagniv"
  }'

Consultar configuração

GET

/v1/webhook-config

Auth

Retorna a configuração de webhook atual.

Resposta 200JSON

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://meu-site.com/webhooks/pagniv",
    "secret": "whsec_****64309a70",
    "isActive": true,
    "createdAt": "2026-01-10T08:00:00Z"
  }
}

Remover webhook

DELETE

/v1/webhook-config

Auth

Remove a configuração de webhook. Nenhuma notificação será mais enviada.

Histórico de entregas

GET

/v1/webhook-deliveries

Auth

Lista entregas de webhook com status, tentativas e resposta do servidor.

Query params

Parâmetro	Tipo	Obrigatório	Descrição
`chargeId`	UUID	Não	Filtrar por cobrança
`status`	string	Não	PENDING, DELIVERED ou FAILED
`page`	integer	Não	Página (padrão: 1)
`limit`	integer	Não	Itens por página (padrão: 20)

Resposta 200JSON

{
  "success": true,
  "data": [
    {
      "id": "...",
      "chargeId": "...",
      "url": "https://meu-site.com/webhooks/pagniv",
      "status": "DELIVERED",
      "attempts": 1,
      "responseStatus": 200,
      "createdAt": "2026-01-15T11:05:02Z"
    }
  ],
  "meta": { "total": 45, "page": 1, "limit": 20, "pages": 3 }
}