Listar deliveries

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/webhooks/deliveries \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/webhooks/deliveries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
  }
}

{
  "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)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

GET

webhooks

deliveries

Listar deliveries

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/webhooks/deliveries \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/webhooks/deliveries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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
  }
}

{
  "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)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

GET /webhooks/deliveries Faz parte do recurso 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).

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, e são no máximo 5. Os intervalos entre as tentativas estão em Entrega e retentativas.

Exemplo

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"

{
  "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.

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Query Parameters

page

integer

default:1

Página da listagem. Padrão: 1.

Required range: x >= 1

limit

integer

default:20

Itens por página. Padrão: 20. Máximo: 100.

Required range: 1 <= x <= 100

webhookId

string

Retorna apenas as entregas deste webhook. Um valor por requisição, correspondência exata.

eventType

string

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.

status

enum<string>

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.

Available options:

pending,

success,

failed,

retrying

isTest

enum<string>

Separa as entregas de teste, disparadas manualmente por você, das entregas reais de eventos. Omitido, traz ambas.

Available options:

true,

false

startDate

string<date-time>

Traz entregas criadas a partir deste instante (ISO 8601 com timezone), inclusive.

endDate

string<date-time>

Traz entregas criadas até este instante (ISO 8601 com timezone), inclusive.

sortBy

enum<string>

Campo de ordenação. Hoje só createdAt. Default: createdAt.

Available options:

createdAt

sortDir

enum<string>

Direção da ordenação: asc ou desc. Default: desc.

Available options:

asc,

desc

Response

Lista paginada de deliveries

data

object[]

Lista de registros retornados na página atual.

Show child attributes

pagination

object

Dados de paginação do resultado.

Show child attributes

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Listar deliveries

Exemplo

Authorizations

Query Parameters

Response

​Exemplo

Authorizations

Query Parameters

Response

Exemplo