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	O PIX é confirmado	charge
charge.refunded	Um estorno é concluído	charge e refund
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:

{
  "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.

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.

Veja também

Verificar a assinatura

O passo que não dá para pular.

Entregas e retentativas

Como deduplicar pelo id do evento.

---

Ficou algo de fora? Escreva para [e-mail]. 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.