Skip to main content
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

1

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.
2

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.
3

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

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
A resposta retorna o endpoint criado (id, endpoint, status, created_at, events). Para atualizar, use o id retornado na listagem em PUT /v1/webhooks/{id}.

​
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.
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.
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 origem: aceite apenas requisições da UvviPay no endpoint de webhook e trate a URL como um segredo operacional.