Catálogo de eventos

Toda notificação de webhook carrega um campo type com o código do evento (ex: transaction.paid). Ao cadastrar um webhook, você escolhe quais códigos deseja receber — ou deixa a lista de eventos vazia para receber todos. Esta página lista todos os eventos disponíveis no catálogo oficial. O mesmo catálogo é exposto pela API em GET /webhooks/listeners, então você pode buscá-lo programaticamente em vez de copiar daqui.

O catálogo autoritativo é sempre GET /webhooks/listeners. Esta página é um espelho para consulta rápida; se houver divergência, confie na resposta do endpoint.

refund.* e chargeback.* são assináveis como qualquer outro código — passe-os no array events normalmente. Os agregados transaction.refunded/payment.refunded e transaction.chargeback/payment.chargeback também existem, e contam histórias diferentes: o evento do recurso segue o ciclo próprio dele (um refund.refused não muda a transação), o agregado avisa o efeito no todo. Já os eventos checkout.session.* são internos do Checkout e não são entregues a webhooks; para saber o resultado de um checkout, escute transaction.paid/transaction.refused.

Códigos de evento são case-sensitive e seguem o padrão recurso.acao em minúsculas com _ para separar palavras (ex: subscription.cycle_advanced). Use exatamente os valores desta página ao preencher o array events na criação do webhook.

Estrutura de uma notificação

Independente do evento, o corpo entregue ao seu endpoint tem sempre o mesmo envelope — id, type, data, occurredAt e companyId. O que muda de um evento para outro é só o conteúdo de data, que é o objeto da entidade que o disparou.

Cada campo do envelope está descrito em Recebendo eventos — inclusive por que o id serve de chave de deduplicação e o occurredAt, de critério de ordem. Esta página cobre o outro lado: quais type existem e o que vem em data para cada um.

{
  "id": "whd_nlb92cdk3doztlw4l7j9a0zi8",
  "type": "transaction.paid",
  "data": {
    "id": "txn_krmzi67pqlu6y78pcly54m26s",
    "status": "paid",
    "amount": 19990,
    "companyId": "comp_g145e2s4m4p9xfaw9jlcn8xpy"
  },
  "occurredAt": "2026-06-24T13:45:10.812Z",
  "companyId": "comp_g145e2s4m4p9xfaw9jlcn8xpy"
}

Se você cadastrou um secret no webhook, cada requisição vem com o header X-Webhook-Signature contendo hex(HMAC-SHA256(secret, rawBody)) calculado sobre o corpo bruto. Veja como validar em Webhooks · Visão geral.

Eventos por recurso

Transação (`transaction.*`)

Eventos do ciclo de vida de uma transação. O campo data traz o objeto da transação (prefixo txn_).

Código	Descrição
`transaction.created`	Transação criada
`transaction.waiting_payment`	Transação aguardando pagamento
`transaction.paid`	Transação paga
`transaction.refused`	Transação recusada
`transaction.failed`	Transação falhou
`transaction.canceled`	Transação cancelada
`transaction.refunded`	Transação reembolsada
`transaction.chargeback`	Transação em chargeback

Pagamento (`payment.*`)

Eventos do ciclo de vida de um pagamento. O campo data traz o objeto do pagamento (prefixo pay_).

Código	Descrição
`payment.created`	Pagamento criado
`payment.waiting_payment`	Pagamento aguardando pagamento
`payment.paid`	Pagamento aprovado
`payment.refused`	Pagamento recusado
`payment.failed`	Pagamento falhou
`payment.refunded`	Pagamento reembolsado
`payment.chargeback`	Pagamento em chargeback

Reembolso (`refund.*`)

Eventos do ciclo próprio do reembolso — pedido, decisão e liquidação. O campo data traz o objeto do reembolso (prefixo rfd_). Os de dados bancários só acontecem em reembolso de boleto, quando é preciso pedir a conta de destino ao comprador.

Código	Descrição
`refund.created`	Reembolso criado
`refund.approved`	Reembolso aprovado
`refund.refused`	Reembolso recusado
`refund.processing`	Reembolso em processamento
`refund.refunded`	Reembolso concluído
`refund.failed`	Reembolso falhou
`refund.awaiting_bank_details`	Reembolso aguardando dados bancários
`refund.bank_details_received`	Dados bancários do reembolso recebidos
`refund.invalid_bank_details`	Dados bancários do reembolso inválidos
`refund.ted_processing`	Reembolso em processamento via TED

O data de todo evento refund.* traz o comprador e o checkout da venda de origem — customerId, customerName, customerEmail, customerDocument, customerDocumentType e additionalInfo.checkoutLinkId (a mesma chave dos eventos transaction.*), copiados da transação quando o estorno é criado. Você sabe de quem é o estorno e de qual checkout veio a venda lendo só o evento, sem consultar a transação. additionalInfo é nulo em venda criada direto pela API, sem link de checkout — veja Reembolsos.

Chargeback (`chargeback.*`)

Eventos do ciclo da contestação — abertura, defesa e desfecho. O campo data traz o objeto do chargeback (prefixo cbk_).

Código	Descrição
`chargeback.opened`	Chargeback aberto
`chargeback.under_review`	Chargeback em análise
`chargeback.submitted`	Defesa do chargeback enviada
`chargeback.won`	Chargeback ganho
`chargeback.lost`	Chargeback perdido
`chargeback.document.uploaded`	Documento do chargeback enviado

Cliente (`customer.*`)

Eventos de cadastro de clientes. O campo data traz o objeto do cliente (prefixo cust_).

Código	Descrição
`customer.created`	Cliente criado
`customer.updated`	Cliente atualizado

Recebedor (`recipient.*`)

Eventos do ciclo de vida do vínculo de um recebedor com a sua conta. O campo data traz os dados cadastrais do recebedor (prefixo rec_), no mesmo formato de GET /recipients/:id — incluindo analysisComplete, pendencies e pendenciesSummary.

Código	Descrição
`recipient.created`	Recebedor criado
`recipient.updated`	Recebedor atualizado
`recipient.approved`	Recebedor aprovado
`recipient.refused`	Recebedor recusado
`recipient.pendency_updated`	Pendências do recebedor atualizadas (rodada de análise fechou sem mudar o status final)
`recipient.deleted`	Recebedor removido

Os eventos de análise (recipient.approved, recipient.refused e recipient.pendency_updated) são disparados uma vez por rodada de análise, quando ela fecha — nunca no meio. O motivo da recusa vem em data.pendencies; veja Por que meu recebedor foi recusado?.

Saque (`withdrawal.*`)

Eventos de saque da carteira (wallet). O campo data traz o objeto do saque.

Código	Descrição
`withdrawal.requested`	Saque solicitado
`withdrawal.paid`	Saque pago
`withdrawal.rejected`	Saque recusado

Fatura (`invoice.*`)

Eventos do ciclo de vida das faturas geradas pelas assinaturas. O campo data traz o objeto da fatura (prefixo inv_).

Código	Descrição
`invoice.issued`	Fatura emitida
`invoice.payment_attempted`	Tentativa de cobrança da fatura
`invoice.paid`	Fatura paga
`invoice.voided`	Fatura anulada
`invoice.refunded`	Fatura reembolsada
`invoice.rescheduled`	Fatura reagendada

No evento invoice.payment_attempted, o data carrega o resultado da tentativa de cobrança (e o invoiceId referenciado), não o objeto completo da fatura.

Não existe status voided no objeto da fatura: o evento invoice.voided é disparado quando a fatura passa para o status canceled (anulada). Ao receber esse evento, espere data.status: "canceled".

Assinatura (`subscription.*`)

Eventos do ciclo de vida das assinaturas. O campo data traz o objeto da assinatura (prefixo sub_).

Código	Descrição
`subscription.created`	Assinatura criada
`subscription.trial_started`	Período de teste da assinatura iniciado
`subscription.activated`	Assinatura ativada
`subscription.canceled`	Assinatura cancelada
`subscription.cycle_advanced`	Novo ciclo da assinatura iniciado
`subscription.paused`	Assinatura pausada
`subscription.resumed`	Assinatura retomada
`subscription.past_due`	Assinatura em atraso (cobrança falhou, ainda em retry)
`subscription.unpaid`	Assinatura inadimplente (atraso passou do limite)
`subscription.restored`	Assinatura regularizada
`subscription.reactivated`	Assinatura reativada manualmente

Se você libera acesso ao seu produto conforme a assinatura, os quatro eventos de inadimplência são o par que interessa:

past_due — a cobrança falhou e a régua de retentativa ainda está rodando. Não é sinal de cortar acesso: a maioria se resolve na próxima tentativa.
unpaid — a régua se esgotou e o motor desistiu. É aqui que faz sentido restringir.
restored — o valor em aberto foi zerado (pagamento ou cancelamento da fatura) e a assinatura voltou para active.
reactivated — o lojista reativou manualmente uma assinatura unpaid.

Quem restringe acesso em past_due ou unpaid precisa ouvir restored e reactivated para liberar de volta — nenhum outro evento avisa que a assinatura voltou.

O que não gera evento: as transições para completed (atingiu maxCycles) e incomplete_expired não têm webhook próprio. Para acompanhá-las, consulte a assinatura na API ou observe os invoice.* das cobranças relacionadas.

Antecipação (`anticipation.*`)

Eventos de antecipação de recebíveis (settle). O campo data traz o objeto da antecipação.

Código	Descrição
`anticipation.status_changed`	Status da antecipação alterado

Buscar o catálogo pela API

Esta mesma lista sai da API, com código e descrição, em GET /webhooks/listeners — útil para validar do seu lado os códigos que você vai assinar, antes de mandá-los no cadastro. Para escolher quais destes eventos um webhook recebe, informe os códigos em events ao criar ou atualizar o webhook. Lista vazia significa todos.

Veja também

Recebendo eventos

Envelope, cabeçalhos e como verificar a assinatura HMAC.

Transações

O objeto transaction enviado nos eventos transaction.*.

Pagamentos

O objeto payment enviado nos eventos payment.*.

Assinaturas

Faturas e assinaturas que disparam os eventos invoice.* e subscription.*.

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Estrutura de uma notificação

Eventos por recurso

Transação (`transaction.*`)

Pagamento (`payment.*`)

Reembolso (`refund.*`)

Chargeback (`chargeback.*`)

Cliente (`customer.*`)

Recebedor (`recipient.*`)

Saque (`withdrawal.*`)

Fatura (`invoice.*`)

Assinatura (`subscription.*`)

Antecipação (`anticipation.*`)

Buscar o catálogo pela API

Veja também

Recebendo eventos

Transações

Pagamentos

Assinaturas

​Estrutura de uma notificação

​Eventos por recurso

​Transação (transaction.*)

​Pagamento (payment.*)

​Reembolso (refund.*)

​Chargeback (chargeback.*)

​Cliente (customer.*)

​Recebedor (recipient.*)

​Saque (withdrawal.*)

​Fatura (invoice.*)

​Assinatura (subscription.*)

​Antecipação (anticipation.*)

​Buscar o catálogo pela API

​Veja também

Recebendo eventos

Transações

Pagamentos

Assinaturas

Estrutura de uma notificação

Eventos por recurso

Transação (`transaction.*`)

Pagamento (`payment.*`)

Reembolso (`refund.*`)

Chargeback (`chargeback.*`)

Cliente (`customer.*`)

Recebedor (`recipient.*`)

Saque (`withdrawal.*`)

Fatura (`invoice.*`)

Assinatura (`subscription.*`)

Antecipação (`anticipation.*`)

Buscar o catálogo pela API

Veja também