> ## 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 deliveries
> Lista paginada das tentativas de entrega de webhooks, com filtros por webhook, evento, situação e período.
`GET /webhooks/deliveries`
Faz parte do recurso [Webhooks](/pt-BR/webhooks) — a configuração e a lista de eventos
estão lá.
Cada entrega é o registro de uma notificação enviada (ou em processo de envio) para a sua URL,
com o payload, a resposta que recebemos e o número de tentativas. Todos os filtros são opcionais e
podem ser combinados; as datas seguem **ISO 8601 com timezone** (veja
[Convenções](/pt-BR/convencoes)).
**Para investigar o que não chegou**, filtre por `status=failed` — são as entregas que esgotaram
as tentativas. `retrying` ainda vai ser reenviada sozinha, e não exige ação sua. O campo
`returnStatus` traz o código HTTP que a sua URL respondeu, e `errorMessage`, o motivo da falha
quando não houve resposta.
**`isTest=false` limpa a contagem.** Os disparos de teste feitos pelo painel viram entregas como
as outras e, sem o filtro, entram misturados nas suas estatísticas de falha. O campo existe só
como filtro: ele **não vem no corpo da resposta**, então a separação se faz na consulta, não
depois.
**`attemptCount` chegando a 7 é o fim do ciclo automático.** Daí em diante a entrega só sai por
[reprocessamento manual](/pt-BR/webhooks/deliveries-retry), e são no máximo 5. Os intervalos
entre as tentativas estão em [Entrega e retentativas](/pt-BR/webhooks/entregas).
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/webhooks/deliveries \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
--data-urlencode "status=failed" \
--data-urlencode "isTest=false" \
--data-urlencode "limit=20"
```
```json theme={null}
{
"data": [
{
"id": "whd_t3ysa1qmxmusn47dhojdraxdi",
"webhookId": "whk_k9clfafnldd96dbbxruh34233",
"eventType": "transaction.paid",
"url": "https://meusite.com/webhooks/z2pay",
"payload": {
"id": "whd_t3ysa1qmxmusn47dhojdraxdi",
"type": "transaction.paid",
"data": { "id": "txn_fcfcvfq9ryd6t3yczj6e87gyh" },
"occurredAt": "2026-06-24T13:46:00.000Z"
},
"status": "failed",
"attemptCount": 7,
"returnStatus": 500,
"returnData": { "error": "internal server error" },
"errorMessage": "Request failed with status code 500",
"lastAttemptAt": "2026-06-24T13:50:12.000Z",
"createdAt": "2026-06-24T13:46:00.000Z",
"updatedAt": "2026-06-24T13:50:12.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}
```
Para reenviar uma entrega que falhou, use
[Reprocessar entrega](/pt-BR/webhooks/deliveries-retry).
## OpenAPI
````yaml openapi/psp.json GET /webhooks/deliveries
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/deliveries:
get:
tags:
- Webhooks
summary: Listar deliveries
description: >-
Retorna lista paginada de entregas de webhook com filtros por status,
evento, etc.
operationId: DeliveryController_list
parameters:
- name: page
in: query
required: false
description: 'Página da listagem. Padrão: 1.'
schema:
type: integer
minimum: 1
default: 1
description: 'Página da listagem. Padrão: 1.'
- name: limit
in: query
required: false
description: 'Itens por página. Padrão: 20. Máximo: 100.'
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: 'Itens por página. Padrão: 20. Máximo: 100.'
- name: webhookId
in: query
required: false
description: >-
Retorna apenas as entregas deste webhook. Um valor por requisição,
correspondência exata.
schema:
type: string
description: >-
Retorna apenas as entregas deste webhook. Um valor por requisição,
correspondência exata.
- name: eventType
in: query
required: false
description: >-
Retorna apenas as entregas deste 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 apenas as entregas deste evento. Um valor por requisição,
correspondência exata (ex.: `transaction.paid`). A lista completa
está em `GET /webhooks/listeners`.
- name: status
in: query
required: false
description: >-
Situação da entrega: `pending` (na fila), `retrying` (falhou e será
reenviada), `success` (respondida com 2xx) ou `failed` (esgotou as
tentativas). Um valor por requisição.
schema:
type: string
enum:
- pending
- success
- failed
- retrying
description: >-
Situação da entrega: `pending` (na fila), `retrying` (falhou e
será reenviada), `success` (respondida com 2xx) ou `failed`
(esgotou as tentativas). Um valor por requisição.
- name: isTest
in: query
required: false
description: >-
Separa as entregas de teste, disparadas manualmente por você, das
entregas reais de eventos. Omitido, traz ambas.
schema:
type: string
enum:
- 'true'
- 'false'
description: >-
Separa as entregas de teste, disparadas manualmente por você, das
entregas reais de eventos. Omitido, traz ambas.
- name: startDate
in: query
required: false
description: >-
Traz entregas criadas a partir deste instante (ISO 8601 com
timezone), inclusive.
schema:
type: string
format: date-time
description: >-
Traz entregas criadas a partir deste instante (ISO 8601 com
timezone), inclusive.
- name: endDate
in: query
required: false
description: >-
Traz entregas criadas até este instante (ISO 8601 com timezone),
inclusive.
schema:
type: string
format: date-time
description: >-
Traz entregas criadas até este instante (ISO 8601 com timezone),
inclusive.
- name: sortBy
in: query
required: false
description: 'Campo de ordenação. Hoje só `createdAt`. Default: `createdAt`.'
schema:
type: string
enum:
- createdAt
description: 'Campo de ordenação. Hoje só `createdAt`. Default: `createdAt`.'
- name: sortDir
in: query
required: false
description: 'Direção da ordenação: `asc` ou `desc`. Default: `desc`.'
schema:
type: string
enum:
- asc
- desc
description: 'Direção da ordenação: `asc` ou `desc`. Default: `desc`.'
responses:
'200':
description: Lista paginada de deliveries
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
webhookId:
type: string
description: ID do webhook relacionado ao registro.
eventType:
type: string
description: 'Tipo do evento entregue (ex.: transaction.paid).'
url:
type: string
description: >-
URL de destino do webhook ou link de download do
arquivo.
payload:
type: object
description: Conteúdo (payload) enviado na entrega do webhook.
status:
type: string
description: >-
Situação da entrega. Valores: `pending`, `success`,
`failed`, `retrying`.
attemptCount:
type: integer
description: Número de tentativas de entrega já realizadas.
returnStatus:
type: integer
nullable: true
description: >-
Código de status HTTP retornado pelo endpoint na
entrega.
returnData:
type: object
nullable: true
description: >-
Corpo da resposta retornada pelo endpoint na
entrega.
errorMessage:
type: string
nullable: true
description: Mensagem de erro quando o processamento falha.
lastAttemptAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora da última tentativa de entrega (ISO
8601).
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).
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.
description: Dados de paginação do resultado.
example:
data:
- id: whd_w2wwfrrrvwx9axbb1wj1bgg75
webhookId: whk_tnuvglgyl74mm7k3cx18mmd6h
eventType: transaction.paid
url: https://api.minhaloja.com.br/webhooks/z2pay
payload:
id: whd_w2wwfrrrvwx9axbb1wj1bgg75
type: transaction.paid
data:
id: txn_wb8adjjeajavewrebxzvv1wna
amount: 9990
status: paid
occurredAt: '2025-06-29T13:46:00.000Z'
status: success
attemptCount: 1
returnStatus: 200
returnData:
received: true
errorMessage: null
lastAttemptAt: '2025-06-29T13:46:01.000Z'
createdAt: '2025-06-29T13:46:00.000Z'
updatedAt: '2025-06-29T13:46:01.000Z'
pagination:
page: 1
limit: 20
total: 1
totalPages: 1
'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)
````