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

# Listar eventos disponíveis

> O catálogo dos códigos de evento que podem ser assinados por um webhook.

`GET /webhooks/listeners`

Faz parte do recurso [Webhooks](/pt-BR/webhooks) — o cadastro e as regras de assinatura estão lá.

Retorna todos os códigos de evento que a Z2Pay emite, cada um com uma descrição curta. É a lista
válida para o campo `events` ao [criar](/pt-BR/webhooks/create) ou
[atualizar](/pt-BR/webhooks/update) um webhook. Não aceita parâmetros e não pagina.

<Note>
  **Use como validação, não como enfeite.** Código fora deste catálogo é recusado com `400` no
  cadastro. Se você monta a lista de eventos a partir de configuração do seu lado, confira contra
  esta resposta antes de enviar — é mais barato que descobrir pelo erro.
</Note>

<Note>
  **O catálogo cresce.** Eventos novos entram aqui sem aviso, e um webhook com `events: []` passa a
  recebê-los automaticamente. Se o seu receptor trata evento desconhecido como erro, prefira
  assinar a lista explícita.
</Note>

Os códigos seguem o padrão `recurso.acao`. O que cada payload carrega está em
[Catálogo de eventos](/pt-BR/webhooks/eventos).

## Exemplo

```bash theme={null}
curl https://api.sandbox.z2pay.com/v1/webhooks/listeners \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```

```json Resposta 200 theme={null}
{
  "data": [
    { "code": "transaction.created", "description": "Transação criada" },
    { "code": "transaction.paid", "description": "Transação paga" },
    { "code": "transaction.refused", "description": "Transação recusada" },
    { "code": "payment.paid", "description": "Pagamento aprovado" },
    { "code": "customer.created", "description": "Cliente criado" },
    { "code": "recipient.approved", "description": "Recebedor aprovado" },
    { "code": "withdrawal.paid", "description": "Saque pago" },
    { "code": "invoice.issued", "description": "Fatura emitida" },
    { "code": "subscription.activated", "description": "Assinatura ativada" }
  ]
}
```

<Note>
  Resposta abreviada: o catálogo completo tem dezenas de códigos, agrupados por recurso em
  [Catálogo de eventos](/pt-BR/webhooks/eventos).
</Note>


## OpenAPI

````yaml openapi/psp.json GET /webhooks/listeners
openapi: 3.0.3
info:
  title: Z2Pay PSP API
  version: 1.0.0
  description: API pública do PSP — autenticação via API Key (Credential)
servers:
  - url: https://api.sandbox.z2pay.com/v1
    description: Sandbox
  - url: https://api.z2pay.com/v1
    description: Produção
security: []
tags:
  - name: Cards
    description: Cartões salvos de um cliente
  - name: Chargebacks
    description: Gerenciamento de chargebacks
  - name: Customers
    description: Gerenciamento de clientes (compradores)
  - name: Fees
    description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
  - name: Recipients
    description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
  - name: Refunds
    description: Gerenciamento de reembolsos e estornos
  - name: Splits
    description: Regras de divisão do valor de uma venda entre recebedores
  - name: Transactions
    description: Gerenciamento de transações e payments
  - name: Wallets
    description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
  - name: Webhooks
    description: Configuração, gerenciamento e histórico de entregas de webhooks
  - name: Withdrawals
    description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
  /webhooks/listeners:
    get:
      tags:
        - Webhooks
      summary: Listar eventos disponíveis
      description: >-
        Retorna o catálogo de todos os eventos que podem ser assinados via
        webhook
      operationId: WebhookController_listeners
      responses:
        '200':
          description: Catálogo de eventos disponíveis
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                          description: Código identificador do item ou do evento.
                        description:
                          type: string
                          description: Descrição do registro.
                        resource:
                          type: string
                        status:
                          type: string
                          enum:
                            - available
                            - planned
                          description: >-
                            Disponibilidade do evento. `available`: já pode ser
                            assinado. `planned`: previsto, ainda não disparado.
                      required:
                        - code
                        - description
                        - resource
                        - status
                    description: Lista de registros retornados na página atual.
                required:
                  - data
        '401':
          description: Chave de API ausente, malformada ou inválida
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: >-
                          Identificador estável do erro. É por ele que você deve
                          ramificar, não pela mensagem.
                      message:
                        type: string
                        description: >-
                          Descrição legível. Pode mudar sem aviso e não deve ser
                          usada em condicional.
              example:
                error:
                  code: UNAUTHORIZED
                  message: Invalid API key
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API Key da Credential (gerada no Backoffice)

````