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

# Catálogo de eventos

> Lista completa dos eventos que você pode assinar via webhook na Z2Pay, agrupados por recurso.

Toda notificação de webhook carrega um campo `type` com o **código do evento** (ex: `transaction.paid`).
Ao [cadastrar um webhook](/pt-BR/webhooks/visao-geral), 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.

<Warning>
  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.
</Warning>

<Info>
  **`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`.
</Info>

<Note>
  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.
</Note>

## 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.

<Note>
  **Cada campo do envelope está descrito em
  [Recebendo eventos](/pt-BR/webhooks/visao-geral#o-envelope-do-evento)** — 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.
</Note>

```json theme={null}
{
  "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"
}
```

<Tip>
  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](/pt-BR/webhooks/visao-geral).
</Tip>

## 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     |

<Note>
  **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](/pt-BR/refunds).
</Note>

### 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                                                                      |

<Note>
  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?](/pt-BR/recipients#por-que-meu-recebedor-foi-recusado).
</Note>

### 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               |

<Info>
  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.
</Info>

<Note>
  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"`.
</Note>

### 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                       |

<Note title="Liberar e cortar acesso pelos eventos de inadimplência">
  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.
</Note>

<Note>
  **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.
</Note>

### 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`](/pt-BR/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](/pt-BR/webhooks/create) ou [atualizar](/pt-BR/webhooks/update) o webhook. Lista vazia
significa **todos**.

## Veja também

<CardGroup cols={2}>
  <Card title="Recebendo eventos" icon="webhook" href="/pt-BR/webhooks/visao-geral">
    Envelope, cabeçalhos e como verificar a assinatura HMAC.
  </Card>

  <Card title="Transações" icon="receipt" href="/pt-BR/transactions">
    O objeto `transaction` enviado nos eventos `transaction.*`.
  </Card>

  <Card title="Pagamentos" icon="credit-card" href="/pt-BR/payments">
    O objeto `payment` enviado nos eventos `payment.*`.
  </Card>

  <Card title="Assinaturas" icon="repeat" href="/pt-BR/subscriptions/visao-geral">
    Faturas e assinaturas que disparam os eventos `invoice.*` e `subscription.*`.
  </Card>
</CardGroup>