Eventos

Todo evento tem três partes, sempre nesta ordem: <recurso>.<método>.<ação>. Ler o nome responde as três perguntas que você faz ao receber a entrega: sobre o que é, por qual rail o dinheiro andou, e o que aconteceu.

charge.pix.paid
│      │   └── ação: o que aconteceu
│      └────── método: por qual rail
└───────────── recurso: sobre o que

charge.boleto.emitted   cobrança, boleto, instrumento pronto
payment.ted.completed   pagamento, TED, dinheiro creditado

Só existem as combinações que fazem sentido. Boleto não sofre chargeback, cartão não tem instrumento emitido nem vence, Pix não passa por autorização em duas etapas. Assinar um nome fora do catálogo devolve 422 no cadastro do endpoint, em vez de aceitar em silêncio um evento que nunca chegaria.

A lista completa também é servida pela API, em GET /v1/webhooks/events, com a descrição de cada evento e o campo dispatched.

Os eventos payment.* descrevem o mesmo recurso servido em /v1/payouts. O nome do evento usa payment por simetria com charge: os dois lados do dinheiro, entrando e saindo, com a mesma gramática de nome.

O data traz object: "dispute", o charge_id da cobrança contestada, o status (open, under_review, won ou lost), o amount bloqueado em centavos, o reason e as datas opened_at, defense_deadline_at e resolved_at.

Os marcados como ainda não disparado existem no catálogo e podem ser assinados desde já: quando a plataforma passar a emiti-los, o endpoint começa a receber sem precisar mexer no cadastro. Até lá, acompanhe o estado por GET /v1/charges/{id} e GET /v1/payouts/{id}.

Na criação de uma cobrança, Pix e boleto disparam os dois: created marca o registro na plataforma, emitted marca o instrumento pronto para o pagador. Hoje os dois acontecem no mesmo instante, porque a cobrança só é devolvida depois que o adquirente entregou o QR code ou a linha digitável.

Assine created se você só quer registrar o pedido, e emitted se o gatilho é mandar o QR code ou o boleto para o cliente. Assinar os dois faz o endpoint receber duas entregas.

A entrega é um POST com corpo JSON. Os headers carregam o evento inteiro e também as partes soltas, para quem roteia a mensagem para uma fila antes de abrir o corpo.

X-Webhook-Event: charge.pix.paid
X-Webhook-Resource: charge
X-Webhook-Method: pix
X-Webhook-Delivery: 4c1d9f80-2b7e-4a11-8c30-9f2a1b3c4d5e
X-Webhook-Signature: sha256=...

{
  "id": "4c1d9f80-2b7e-4a11-8c30-9f2a1b3c4d5e",
  "object": "event",
  "event": "charge.pix.paid",
  "resource": "charge",
  "method": "pix",
  "action": "paid",
  "created_at": "2026-07-28T14:03:11.000Z",
  "data": {
    "object": "charge",
    "id": "8f1c2a90-1f4b-4f0e-9d33-5a2c1b7e9a10",
    "status": "paid",
    "method": "pix",
    "amount": 4990,
    "currency": "BRL",
    "reference": "pedido-1042",
    "created_at": "2026-07-28T14:00:00.000Z"
  }
}

{
  "id": "b2790cf1-55a3-4a7d-9a02-1f6d4e8c3b77",
  "object": "event",
  "event": "payment.ted.created",
  "resource": "payment",
  "method": "ted",
  "action": "created",
  "created_at": "2026-07-28T15:10:00.000Z",
  "data": {
    "object": "payment",
    "id": "9d55a0b2-3c11-4e77-b0a1-72f9c4d10e3a",
    "status": "pending",
    "method": "ted",
    "amount": 250000,
    "currency": "BRL",
    "reference": "lote-3",
    "created_at": "2026-07-28T15:10:00.000Z"
  }
}

Responda 2xx assim que receber, antes de processar. Todo o trabalho pesado, consulta a banco, envio de e-mail, deve acontecer depois da resposta: um handler lento vira timeout e a entrega é marcada como falha.

Trate as entregas como possivelmente repetidas. Use X-Webhook-Delivery para descartar o que já processou, ou torne o efeito idempotente pelo id em data.id.