> ## 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 webhooks
> Lista paginada dos webhooks da sua conta, com filtro por ativação e por evento assinado.
`GET /webhooks`
Faz parte do recurso [Webhooks](/pt-BR/webhooks) — a configuração e o catálogo de eventos
estão lá.
Retorna a lista paginada dos webhooks da sua conta. Os dois filtros são opcionais e podem ser
combinados.
**`event` responde "quem seria notificado se isso acontecesse".** Ele traz os webhooks inscritos
naquele evento, com correspondência exata e um valor por requisição — `?event=transaction.paid`.
A lista de eventos válidos está em
[Listar eventos disponíveis](/pt-BR/webhooks/listeners).
**O `secret` não vem nesta resposta** — nem em nenhuma outra leitura. Ele sai em claro uma única
vez, na [criação do webhook](/pt-BR/webhooks/create). Aqui vêm no lugar `hasSecret`, que confirma
que o webhook assina as entregas, e `secretHint`, um fragmento para você reconhecer qual segredo
está configurado.
Perdeu o valor? Não há como relê-lo, e **nenhuma rota o troca**: a rotação é feita no painel. Pela
API, o equivalente é criar outro webhook com o mesmo destino e remover o antigo.
**`autoDisabledAt` preenchido é um alarme.** Significa que a Z2Pay desativou aquele webhook por
falhas seguidas, e nada está sendo entregue nele desde então. Vale uma varredura periódica por
este campo — o critério está em
[Entrega e retentativas](/pt-BR/webhooks/entregas#desativa-o-autom-tica).
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/webhooks -H "x-api-key: SUA_CHAVE_DE_SANDBOX" --data-urlencode "isActive=true" --data-urlencode "limit=20"
```
```json theme={null}
{
"data": [
{
"id": "whk_k9clfafnldd96dbbxruh34233",
"name": "Notificações de pagamento",
"url": "https://meusite.com/webhooks/z2pay",
"events": ["transaction.paid", "transaction.refunded"],
"isActive": true,
"hasSecret": true,
"secretHint": "whsec_kQ8v…rS8t",
"autoDisabledAt": null,
"createdAt": "2026-06-24T13:45:00.000Z",
"updatedAt": "2026-06-24T13:45:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}
```
## OpenAPI
````yaml openapi/psp.json GET /webhooks
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:
get:
tags:
- Webhooks
summary: Listar webhooks
description: Retorna lista paginada de webhooks configurados para a company
operationId: WebhookController_list
parameters:
- name: isActive
in: query
required: false
description: >-
Filtra por webhooks ativos (`true`) ou inativos (`false`). Omitido,
traz ambos.
schema:
type: string
enum:
- 'true'
- 'false'
description: >-
Filtra por webhooks ativos (`true`) ou inativos (`false`).
Omitido, traz ambos.
- name: event
in: query
required: false
description: >-
Retorna os webhooks inscritos neste evento. Um valor por requisição,
correspondência exata (ex.: `transaction.paid`). A lista completa
está em `GET /webhooks/listeners`.
schema:
type: string
description: >-
Retorna os webhooks inscritos neste evento. Um valor por
requisição, correspondência exata (ex.: `transaction.paid`). A
lista completa está em `GET /webhooks/listeners`.
- name: page
in: query
required: false
schema:
type: integer
minimum: 0
exclusiveMinimum: true
default: 1
description: Número da página a retornar.
- name: limit
in: query
required: false
schema:
type: integer
minimum: 0
exclusiveMinimum: true
maximum: 100
default: 20
description: Quantidade de itens por página.
responses:
'200':
description: Lista paginada de webhooks
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
name:
type: string
description: Nome do registro.
url:
type: string
format: uri
description: >-
URL de destino do webhook ou link de download do
arquivo.
events:
type: array
items:
type: string
description: Tipos de evento assinados pelo webhook.
isActive:
type: boolean
description: Indica se o registro está ativo.
hasSecret:
type: boolean
secretHint:
type: string
nullable: true
autoDisabledAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Data e hora da última atualização do registro (ISO
8601).
required:
- id
- name
- url
- events
- isActive
- hasSecret
- secretHint
- autoDisabledAt
- createdAt
- updatedAt
description: Lista de registros retornados na página atual.
pagination:
type: object
properties:
page:
type: integer
description: Página atual retornada.
limit:
type: integer
description: Quantidade de itens por página.
total:
type: integer
description: Total de itens que atendem ao filtro.
totalPages:
type: integer
description: Total de páginas disponíveis.
required:
- page
- limit
- total
- totalPages
description: Dados de paginação do resultado.
required:
- data
- pagination
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
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.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'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)
````