Catálogo de eventos

São 17 tipos públicos, em três famílias, mais o ping. Um endpoint assina os tipos que quiser, ou ["*"] para todos os públicos.

Todos chegam no mesmo envelope, descrito em webhooks: id, object: "event", type, mode, created_at e data.object. O que muda de um tipo para outro é o type e o recurso que vem em data.object.

Cobranças

data.object é a cobrança no estado em que ela ficou, no mesmo formato de Consulta uma cobrança.

Tipo	Quando é emitido
`transaction.paid`	O pagamento entrou. É o evento que libera o pedido
`transaction.expired`	O prazo acabou sem pagamento. Não é estado final: ver abaixo
`transaction.failed`	A cobrança não chegou a ficar pagável (o processador recusou ou não respondeu)
`transaction.refunded`	Estorno concluído
`transaction.chargeback`	Contestação perdida. O valor volta a ser debitado do saldo
`transaction.reserve_released`	A parte retida em reserva daquela cobrança virou saldo disponível

transaction.expired seguido de transaction.paid na mesma cobrança é situação normal, não erro: o prazo é um pedido ao banco do pagador, e pagamento tardio acontece. Trate em idempotência e ordem.

transaction.created não é entregue por webhook, nem para quem assina ["*"]. A criação da cobrança é a resposta síncrona de Cria uma cobrança PIX: você já tem o objeto em mãos e não precisa de um evento para saber que ela existe.

Saques

data.object é o saque, no mesmo formato de Consulta um saque.

Tipo	Quando é emitido
`withdrawal.awaiting`	Saque criado, aguardando aprovação
`withdrawal.approved`	Aprovado, na fila para ser executado
`withdrawal.rejected`	Recusado na aprovação. O valor volta para o saldo disponível
`withdrawal.cancelled`	Cancelado por você antes da aprovação. O valor volta para o saldo
`withdrawal.processing`	Enviado ao parceiro de pagamento
`withdrawal.successful`	Liquidado. O dinheiro saiu para a chave PIX
`withdrawal.failed`	O parceiro recusou ou a transferência não completou. O valor volta para o saldo

O caminho feliz é awaiting, approved, processing, successful. Numa conta com aprovação automática de saque o withdrawal.awaiting não existe: o saque já nasce aprovado e o primeiro evento é o withdrawal.approved. rejected, cancelled, successful e failed são finais.

Conta

data.object é o seller, a mesma base que Perfil do seller da sessão (documento sempre mascarado) devolve.

Tipo	Quando é emitido
`seller.kyc_approved`	Cadastro aprovado. A partir daqui a conta opera em `live`
`seller.kyc_rejected`	Cadastro recusado. O motivo aparece no painel
`seller.payout_locked`	Saques bloqueados por análise. Cobranças continuam funcionando
`seller.payout_unlocked`	Bloqueio de saque removido

Ping

ping não é assinável e não entra em ["*"]. Ele só sai quando você pede um teste para um endpoint específico, e chega assinado como qualquer outro evento. data.object traz apenas endpoint_id e url.

Um envelope inteiro

Exemplo de transaction.paid como ele chega no seu servidor. Os outros tipos têm exatamente a mesma forma, trocando type e o conteúdo de data.object:

{
  "id": "evt_01j9x5k8p2q3r4s5t6u7v8w9xy",
  "object": "event",
  "type": "transaction.paid",
  "mode": "live",
  "created_at": "2026-09-10T12:04:31Z",
  "data": {
    "object": {
      "id": "txn_01j9x5k8p2q3r4s5t6u7v8w9xy",
      "object": "transaction",
      "mode": "live",
      "status": "paid",
      "payment_method": "pix",
      "amount": 10000,
      "fee": 699,
      "net": 9301,
      "reserve": 930,
      "customer": { "name": "Maria Silva", "email": "[email protected]" },
      "metadata": { "order_id": "A123" },
      "paid_at": "2026-09-10T12:04:30Z",
      "end_to_end_id": "E1234567820260910120430abcdef123",
      "created_at": "2026-09-10T12:00:00Z"
    }
  }
}

O data.object acima está encurtado para caber na página. A lista completa de campos de cada recurso, com tipos e valores possíveis, está na referência da API, que é a fonte de verdade: nenhuma página desta documentação repete campo.

Tipo novo aparece sem aviso

Tipo de evento novo é mudança aditiva e entra sem /v2. Um receptor correto ignora o que não conhece e responde 2xx; se ele devolver 400, a entrega é retentada, e um endpoint que recusa todo evento novo acaba desativado automaticamente.

Se você quer receber só alguns tipos, liste-os em events no endpoint em vez de filtrar com erro do seu lado.