Webhooks - UvviPay Public API

Os webhooks permitem que a UvviPay notifique o seu sistema automaticamente quando algo relevante acontece na sua operação. Em vez de ficar consultando a API repetidamente, você registra uma URL e passa a receber uma requisição POST a cada notificação.

Como funciona

Você registra um endpoint

Informe uma URL HTTPS através da API de webhooks. O endpoint fica vinculado à organização das credenciais CLIENT-ID / CLIENT-SECRET usadas na requisição e é inscrito automaticamente em todos os tipos de notificação (event) disponíveis para essa organização.

A UvviPay envia as notificações

Quando algo relevante ocorre, enviamos uma requisição POST com o corpo em JSON para a sua URL. O cabeçalho User-Agent das nossas chamadas é UVVIPay-Webhook/1.0.

Seu sistema confirma o recebimento

Responda com um status HTTP 2xx para confirmar. Qualquer outra resposta, ou um tempo de resposta acima de 30 segundos, é tratada como falha.

Limites

Regra	Valor
Máximo de endpoints por organização	3
Protocolo da URL	Somente HTTPS
Timeout por tentativa	30 segundos
Tentativas de reenvio	3 (com backoff exponencial)

Cada endpoint é inscrito automaticamente em todos os tipos de notificação disponíveis; ainda não é possível assinar tipos individuais por URL. Na entrega, cada event segue regras de audiência da plataforma (por exemplo, notificações da organização do merchant, da subconta envolvida, ou de ambas), o que determina quais endpoints recebem o POST.

Gerenciando webhooks

A gestão é feita pelos endpoints autenticados com CLIENT-ID / CLIENT-SECRET:

Criar

Registre uma nova URL de webhook

Atualizar

Altere a URL e os eventos de um webhook existente

Listar

Consulte os webhooks ativos e seus ids

Criando um webhook

POST /v1/webhooks

{
  "webhook_url": "https://minhaloja.com.br/webhooks/uvvipay",
  "events": ["transaction.paid", "transaction.refused"],
  "hmac_secret": "seu-segredo-compartilhado"
}

O campo hmac_secret é opcional. Quando informado (de 16 a 256 caracteres), a UvviPay armazena o valor de forma cifrada e assina cada entrega com HMAC-SHA256. A resposta retorna o endpoint criado (id, endpoint, status, created_at, events, hmac_configured). O secret nunca é devolvido nas respostas. Para atualizar, use o id retornado na listagem em PUT /v1/webhooks/{id}:

enviar hmac_secret (string): cadastra ou substitui o secret
omitir hmac_secret: mantém o secret atual
enviar hmac_secret: null: desliga a assinatura HMAC (limpa o secret; próximas entregas não enviam os headers)

Eventos de transação

Prefira assinar os eventos por status. O evento genérico transaction.status.updated continua disponível por retrocompatibilidade e é disparado junto com o evento específico em cada mudança de status.

Evento	Quando dispara
`transaction.waiting_payment`	Transação aguardando pagamento
`transaction.paid`	Transação paga
`transaction.refused`	Transação recusada
`transaction.refunded`	Transação estornada
`transaction.chargedback`	Transação com chargeback
`transaction.cancelled`	Transação cancelada
`transaction.expired`	Transação expirada
`transaction.in_analysis`	Transação em análise
`transaction.status.updated`	Qualquer mudança de status (retrocompat)

Boleto no payload

Se paymentMethod for boleto, o payload inclui boleto.digitableLine. O webhook não envia url nem barcode. Consulte o PDF em GET /v1/payments/{id}/boleto.

Se o mesmo endpoint assinar o genérico e um evento específico, receberá duas requisições HTTP com o mesmo conteúdo; a diferença fica no campo event. Endpoints já cadastrados não passam a receber eventos novos automaticamente; inclua-os no create/update.

Formato das notificações

Todo payload enviado para o seu endpoint inclui o campo event, que identifica o tipo da notificação. O restante do corpo varia conforme o contexto. Trate cada event no seu sistema e ignore tipos que você ainda não processa.

{
  "event": "tipo.da.notificacao",
  "...": "demais campos conforme o contexto"
}

Quando o endpoint tiver hmac_secret cadastrado, a entrega inclui os cabeçalhos:

X-UvviPay-Timestamp: <unix_seconds>
X-UvviPay-Signature: sha256=<hex>

A assinatura é o HMAC-SHA256 de timestamp + "." + body (body JSON bruto), usando o secret informado no cadastro. Rejeite a requisição se |now - timestamp| for maior que 300 segundos (5 minutos) ou se a assinatura não bater. Exemplo de verificação no seu backend:

const crypto = require("crypto");

const TOLERANCE_SECONDS = 300;

function verify(rawBody, signatureHeader, timestampHeader, secret) {
  const timestamp = Number(timestampHeader);
  if (!Number.isFinite(timestamp)) {
    return false;
  }

  const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (ageSeconds > TOLERANCE_SECONDS) {
    return false;
  }

  const signedPayload = `${timestamp}.${rawBody}`;
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(signedPayload).digest("hex");

  const expectedBuf = Buffer.from(expected);
  const receivedBuf = Buffer.from(signatureHeader);
  if (expectedBuf.length !== receivedBuf.length) {
    return false;
  }

  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}

Use o body exatamente como chegou (sem reformatar o JSON).

Novos tipos de notificação podem ser adicionados ao longo do tempo. Projete sua integração para ser extensível: valide o campo event e processe apenas o que for relevante para o seu caso de uso.

Boas práticas

Responda rápido: confirme com 2xx o quanto antes e processe a notificação de forma assíncrona no seu lado.
Seja idempotente: a mesma notificação pode ser reentregue em caso de falha. Use identificadores estáveis do payload para evitar processamento duplicado.
Valide a assinatura: quando cadastrar hmac_secret, verifique X-UvviPay-Timestamp e X-UvviPay-Signature (material timestamp.body) e rejeite timestamps fora da janela de 300s.
Valide a origem: aceite apenas requisições da UvviPay no endpoint de webhook e trate a URL e o secret como segredos operacionais.

​Como funciona

​Limites

​Gerenciando webhooks

Criar

Atualizar

Listar

​Criando um webhook

​Eventos de transação

​Boleto no payload

​Formato das notificações

​Boas práticas

Como funciona

Limites

Gerenciando webhooks

Criando um webhook

Eventos de transação

Boleto no payload

Formato das notificações

Boas práticas