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

# Visão geral dos webhooks

> Os três eventos que enviamos, como cadastrar endpoints e o que responder.

Webhooks são as chamadas que **nós** fazemos para o seu sistema quando algo acontece. É por eles que
você descobre que um PIX foi pago sem ficar perguntando.

| Evento                                                       | Quando dispara                   | O que vem em `data` |
| ------------------------------------------------------------ | -------------------------------- | ------------------- |
| [`charge.paid`](/api-reference/webhooks/charge-paid)         | O PIX é confirmado               | `charge`            |
| [`charge.refunded`](/api-reference/webhooks/charge-refunded) | Um estorno é concluído           | `charge` e `refund` |
| [`withdrawal.paid`](/api-reference/webhooks/withdrawal-paid) | O saque cai na conta do vendedor | `withdrawal`        |

`charge.paid` é o evento sobre o qual o seu sistema deve agir: liberar acesso, faturar, dar baixa no
pedido.

## Cadastro

Você cadastra vários endpoints em **Desenvolvedores**. Produção e homologação são sistemas
diferentes, e cada um recebe só os eventos que assinou, com o **seu próprio segredo de assinatura**.

Um segredo por endpoint significa que o segredo de homologação vazado não permite forjar eventos em
produção.

## O envelope

Todo evento tem a mesma forma:

```json theme={null}
{
  "id": "evt_01k1y6r7z2m4n6p8q0r2s4t6u8",
  "type": "charge.paid",
  "created_at": "2026-08-04T14:03:12+00:00",
  "data": {
    "charge": { "object": "charge", "id": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2", "status": "paid" }
  }
}
```

E três headers:

| Header             | Para quê                                                                           |
| ------------------ | ---------------------------------------------------------------------------------- |
| `X-Vext-Signature` | `t=<timestamp>,v1=<hmac>`. **Confira antes de agir**                               |
| `X-Vext-Event`     | O tipo, repetido fora do corpo — permite filtrar no seu log sem desserializar nada |
| `X-Vext-Delivery`  | Identificador da entrega. Cite-o ao abrir um chamado                               |

## Uma entrega por fato

Cada fato vira no máximo **uma** entrega por endpoint. Uma reentrega do provedor para nós não vira
uma segunda entrega para você.

Uma entrega que desistiu depois das retentativas pode ser reenviada à mão pelo painel — e aí o `id`
do evento é o **mesmo**, para a sua idempotência reconhecê-lo.

## O que responder

Qualquer `2xx` encerra a entrega. Qualquer coisa fora dessa faixa agenda nova tentativa.

<Note>
  Grave o evento, responda `200` e deixe o processamento para uma fila. Responder rápido é o que
  evita que a retentativa chegue enquanto você ainda processa o primeiro. O padrão completo está em
  [Entregas e retentativas](/webhooks/entregas-e-retentativas).
</Note>

## Veja também

<CardGroup cols={2}>
  <Card title="Verificar a assinatura" icon="shield-check" href="/webhooks/assinatura">
    O passo que não dá para pular.
  </Card>

  <Card title="Entregas e retentativas" icon="repeat" href="/webhooks/entregas-e-retentativas">
    Como deduplicar pelo `id` do evento.
  </Card>
</CardGroup>

***

Ficou algo de fora? Escreva para [suporte@usevext.com](mailto:suporte@usevext.com). Se o assunto for
uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o
`X-Vext-Delivery` — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.