> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uvvipay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba notificações em tempo real no contexto da sua organização registrando endpoints de webhook

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

| 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) |

> [!NOTE]
>
> 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`:

> [card] [Criar](https://developers.uvvipay.com.br/api-reference/webhooks/create.md)
>
> Registre uma nova URL de webhook

> [card] [Atualizar](https://developers.uvvipay.com.br/api-reference/webhooks/update.md)
>
> Altere a URL e os eventos de um webhook existente

> [card] [Listar](https://developers.uvvipay.com.br/api-reference/webhooks/get.md)
>
> Consulte os webhooks ativos e seus ids

### Criando um webhook

```json POST /v1/webhooks theme={null}
{
  "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`.

> [!NOTE]
>
> 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.

```json theme={null}
{
  "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:

```js theme={null}
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).

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.