Buscar delivery por ID

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/webhooks/deliveries/{id} \
  --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/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "whd_w2wwfrrrvwx9axbb1wj1bgg75",
  "webhookId": "whk_tnuvglgyl74mm7k3cx18mmd6h",
  "eventType": "transaction.refused",
  "url": "https://api.minhaloja.com.br/webhooks/z2pay",
  "payload": {
    "id": "whd_w2wwfrrrvwx9axbb1wj1bgg75",
    "type": "transaction.refused",
    "data": {
      "id": "txn_wb8adjjeajavewrebxzvv1wna",
      "amount": 9990,
      "status": "refused"
    },
    "occurredAt": "2025-06-29T13:50:00.000Z"
  },
  "status": "failed",
  "attemptCount": 3,
  "returnStatus": 500,
  "returnData": {
    "error": "Internal Server Error"
  },
  "errorMessage": "Request failed with status code 500",
  "lastAttemptAt": "2025-06-29T14:02:30.000Z",
  "createdAt": "2025-06-29T13:50:00.000Z",
  "updatedAt": "2025-06-29T14:02:30.000Z"
}

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

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Delivery not found"
  }
}

GET

webhooks

deliveries

{id}

Buscar delivery por ID

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/webhooks/deliveries/{id} \
  --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/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "whd_w2wwfrrrvwx9axbb1wj1bgg75",
  "webhookId": "whk_tnuvglgyl74mm7k3cx18mmd6h",
  "eventType": "transaction.refused",
  "url": "https://api.minhaloja.com.br/webhooks/z2pay",
  "payload": {
    "id": "whd_w2wwfrrrvwx9axbb1wj1bgg75",
    "type": "transaction.refused",
    "data": {
      "id": "txn_wb8adjjeajavewrebxzvv1wna",
      "amount": 9990,
      "status": "refused"
    },
    "occurredAt": "2025-06-29T13:50:00.000Z"
  },
  "status": "failed",
  "attemptCount": 3,
  "returnStatus": 500,
  "returnData": {
    "error": "Internal Server Error"
  },
  "errorMessage": "Request failed with status code 500",
  "lastAttemptAt": "2025-06-29T14:02:30.000Z",
  "createdAt": "2025-06-29T13:50:00.000Z",
  "updatedAt": "2025-06-29T14:02:30.000Z"
}

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

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Delivery not found"
  }
}

GET /webhooks/deliveries/:id Faz parte do recurso Webhooks — o cadastro e o catálogo de eventos estão lá. Retorna uma entrega inteira, com o payload exato que enviamos e o que voltou do seu servidor. É a leitura de depuração: quando algo “não chegou”, é aqui que se vê se saiu, para onde, e o que o seu endpoint respondeu.

Três campos respondem “de quem é a culpa”. returnStatus é o HTTP que o seu servidor devolveu; returnData, o corpo dessa resposta; errorMessage, o motivo quando não houve resposta nenhuma (timeout, DNS, conexão recusada). returnStatus: null com errorMessage preenchido significa que a requisição não chegou a ser respondida.

payload é o envelope como o seu servidor o recebeu — mesmo id, mesmo occurredAt. Um reenvio não regrava esses valores, o que é justamente o que permite deduplicar pelo id e descartar evento antigo pelo occurredAt. O formato está em Recebendo eventos.

attemptCount conta todas as tentativas daquela entrega, automáticas e manuais. Chegando a 7, o ciclo automático se esgotou; daí em diante só cresce por reprocessamento.

Exemplo

curl https://api.sandbox.z2pay.com/v1/webhooks/deliveries/whd_t3ysa1qmxmusn47dhojdraxdi \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Resposta 200

{
  "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-25T20:16:00.000Z",
  "createdAt": "2026-06-24T13:46:00.000Z",
  "updatedAt": "2026-06-25T20:16:00.000Z"
}

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Path Parameters

string

required

ID da delivery

Response

Dados da delivery

string

Identificador único do registro.

webhookId

string

ID do webhook relacionado ao registro.

eventType

string

Tipo do evento entregue (ex.: transaction.paid).

url

string

URL de destino do webhook ou link de download do arquivo.

payload

object

Conteúdo (payload) enviado na entrega do webhook.

status

string

Situação da entrega. Valores: pending, success, failed, retrying.

attemptCount

integer

Número de tentativas de entrega já realizadas.

returnStatus

integer | null

Código de status HTTP retornado pelo endpoint na entrega.

returnData

object | null

Corpo da resposta retornada pelo endpoint na entrega.

errorMessage

string | null

Mensagem de erro quando o processamento falha.

lastAttemptAt

string<date-time> | null

Data e hora da última tentativa de entrega (ISO 8601).

createdAt

string<date-time>

Data e hora de criação do registro (ISO 8601).

updatedAt

string<date-time>

Data e hora da última atualização do registro (ISO 8601).

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Buscar delivery por ID

Exemplo

Authorizations

Path Parameters

Response

​Exemplo

Authorizations

Path Parameters

Response

Exemplo