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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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`.
</Note>

## Gerenciando webhooks

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

<CardGroup cols={3}>
  <Card title="Criar" href="/api-reference/webhooks/create">
    Registre uma nova URL de webhook
  </Card>

  <Card title="Atualizar" href="/api-reference/webhooks/update">
    Altere a URL e os eventos de um webhook existente
  </Card>

  <Card title="Listar" href="/api-reference/webhooks/get">
    Consulte os webhooks ativos e seus ids
  </Card>
</CardGroup>

### Criando um webhook

```json POST /v1/webhooks theme={null}
{
  "webhook_url": "https://minhaloja.com.br/webhooks/uvvipay",
  "events": ["transaction.paid", "transaction.refused"]
}
```

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.

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

<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.
</Note>

## 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"
}
```

<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.
</Note>

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