Webhooks

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 webhook_url e events (ao menos um) em POST /v1/webhooks. O endpoint fica vinculado à organização das credenciais CLIENT-ID / CLIENT-SECRET. O endpoint recebe só os eventos do array events.

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 ativos por organização	10
Protocolo da URL	Somente HTTPS
Timeout por tentativa	30 segundos
Tentativas de reenvio	3 (com backoff exponencial)

POST /v1/webhooks exige events. Evento novo entra no create ou no PUT /v1/webhooks/{id}. Endpoint já cadastrado não passa a receber evento novo sozinho.

Na entrega, cada event segue regras de audiência. O POST vai para a organização do merchant, para a subconta envolvida, ou para ambas.

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.

O status da resposta (active, failed, inactive, suspended) é do endpoint. Não é status de subconta.

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)

Eventos de subconta

Evento	Quando dispara
`submerchant.status.updated`	O status da subconta muda

O campo status do corpo é o status da subconta. Não é o status do onboarding (processing, approved, rejected, action_required). Exemplo:

{
  "event": "submerchant.status.updated",
  "id": "5b9f3d6a-3a2c-4d6f-9b9e-0a1b2c3d4e5f",
  "status": "documentation_pending"
}

O campo id é o internalId da subconta. Inclua submerchant.status.updated no events do create ou do PUT /v1/webhooks/{id}. Endpoint já cadastrado não passa a receber esse evento sozinho.

suspended é status do endpoint de webhook (active, failed, inactive, suspended). Não é status de subconta.

Eventos de assinatura

Os eventos subscription.* estão em Recorrência. Inclua cada evento no events do create ou do update.

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.

Começando

Funcionalidades

Como funciona

Limites

Gerenciando webhooks

Criar

Atualizar

Listar

Criando um webhook

Eventos de transação

Eventos de subconta

Eventos de assinatura

Boleto no payload

Formato das notificações

Boas práticas

Começando

Funcionalidades

​Como funciona

​Limites

​Gerenciando webhooks

Criar

Atualizar

Listar

​Criando um webhook

​Eventos de transação

​Eventos de subconta

​Eventos de assinatura

​Boleto no payload

​Formato das notificações

​Boas práticas

Como funciona

Limites

Gerenciando webhooks

Criando um webhook

Eventos de transação

Eventos de subconta

Eventos de assinatura

Boleto no payload

Formato das notificações

Boas práticas