Pular para o conteúdo principal
Webhooks notificam o seu sistema em tempo real quando algo acontece na Z2Pay (uma transação foi paga, um saque foi rejeitado, uma fatura foi emitida, etc.). Esta página cobre o gerenciamento dos webhooks (CRUD) e o histórico de entregas (deliveries).
Para entender o conceito de assinatura de eventos, formato do payload e como validar a assinatura recebida, veja Webhooks: visão geral e Catálogo de eventos.
Todas as requisições exigem o header x-api-key. Veja Autenticação.

​
Endpoints

​
Configuração de webhooks

MétodoRotaDescrição
POST/webhooksCriar um webhook
GET/webhooksListar webhooks (paginado)
GET/webhooks/listenersListar o catálogo de eventos disponíveis
GET/webhooks/:idBuscar um webhook por ID
PUT/webhooks/:idAtualizar um webhook
PATCH/webhooks/:id/statusAtivar ou desativar um webhook
DELETE/webhooks/:idRemover um webhook (soft delete)

​
Histórico de entregas (deliveries)

MétodoRotaDescrição
GET/webhooks/deliveriesListar entregas (paginado, com filtros)
GET/webhooks/deliveries/:idBuscar uma entrega por ID
POST/webhooks/deliveries/:id/retryReprocessar uma entrega
A URL do webhook precisa usar HTTPS e apontar para um host público. URLs que resolvem para localhost, faixas de IP privadas (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local/metadata de cloud (169.254.0.0/16, metadata.google.internal) ou esquemas que não sejam http/https são rejeitadas com 400. Isso protege contra SSRF.

​
Criar webhook

POST /webhooks Registra um novo webhook. Retorna 201 com o webhook criado.
​
name
string
obrigatório
Nome de identificação do webhook. Entre 1 e 255 caracteres.
​
url
string
obrigatório
URL HTTPS pública que receberá as notificações. URLs internas/privadas são rejeitadas (veja o aviso acima).
​
events
string[]
padrão:"[]"
Lista de eventos a assinar. Cada valor deve ser um código do catálogo de eventos. Se enviado vazio (ou omitido), o webhook escuta TODOS os eventos.
​
secret
string
Segredo usado para assinar o payload das entregas. Mínimo de 8 caracteres. Opcional. Veja validação de assinatura.
Este endpoint aceita o header Idempotency-Key para evitar criações duplicadas. Veja Convenções. 
curl -X POST https://api.sandbox.z2pay.com/webhooks \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c8a90-2b7d-4d2e-9b1a-6f0e2c5a9d11" \
  -d '{
    "name": "Notificações de pagamento",
    "url": "https://meusite.com/webhooks/z2pay",
    "events": ["transaction.paid", "transaction.refunded"],
    "secret": "um-segredo-bem-grande"
  }'

{
  "id": "whk_8Hk2pQ7rT9vLm3Nx",
  "companyId": "comp_4Zp1Yt6Bn0Wq",
  "name": "Notificações de pagamento",
  "url": "https://meusite.com/webhooks/z2pay",
  "events": ["transaction.paid", "transaction.refunded"],
  "secret": "um-segredo-bem-grande",
  "isActive": true,
  "createdAt": "2026-06-24T13:45:00.000Z",
  "updatedAt": "2026-06-24T13:45:00.000Z",
  "deletedAt": null,
  "version": 1
}

​
Listar webhooks

GET /webhooks Retorna uma lista paginada dos webhooks da sua conta.
Parâmetro (query)TipoObrigatórioDescrição
isActivebooleanNãoFiltra por status ativo/inativo.
eventstringNãoFiltra webhooks que escutam um evento específico (ex: transaction.paid).
pageintegerNãoPágina (inteiro positivo). Padrão 1.
limitintegerNãoItens por página (inteiro positivo, máximo 100). Padrão 20.
curl -X GET "https://api.sandbox.z2pay.com/webhooks?isActive=true&page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "whk_8Hk2pQ7rT9vLm3Nx",
      "companyId": "comp_4Zp1Yt6Bn0Wq",
      "name": "Notificações de pagamento",
      "url": "https://meusite.com/webhooks/z2pay",
      "events": ["transaction.paid", "transaction.refunded"],
      "secret": "um-segredo-bem-grande",
      "isActive": true,
      "createdAt": "2026-06-24T13:45:00.000Z",
      "updatedAt": "2026-06-24T13:45:00.000Z",
      "deletedAt": null,
      "version": 1
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

​
Listar eventos disponíveis

GET /webhooks/listeners Retorna o catálogo completo de eventos que podem ser assinados. Use os valores de code no campo events ao criar ou atualizar um webhook. Não aceita parâmetros. 
curl -X GET https://api.sandbox.z2pay.com/webhooks/listeners \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    { "code": "transaction.created", "description": "Transação criada" },
    { "code": "transaction.waiting_payment", "description": "Transação aguardando pagamento" },
    { "code": "transaction.paid", "description": "Transação paga" },
    { "code": "transaction.refused", "description": "Transação recusada" },
    { "code": "transaction.failed", "description": "Transação falhou" },
    { "code": "transaction.canceled", "description": "Transação cancelada" },
    { "code": "transaction.refunded", "description": "Transação reembolsada" },
    { "code": "transaction.chargeback", "description": "Transação em chargeback" },
    { "code": "payment.created", "description": "Pagamento criado" },
    { "code": "payment.waiting_payment", "description": "Pagamento aguardando pagamento" },
    { "code": "payment.paid", "description": "Pagamento aprovado" },
    { "code": "payment.refused", "description": "Pagamento recusado" },
    { "code": "payment.failed", "description": "Pagamento falhou" },
    { "code": "payment.refunded", "description": "Pagamento reembolsado" },
    { "code": "payment.chargeback", "description": "Pagamento em chargeback" },
    { "code": "customer.created", "description": "Cliente criado" },
    { "code": "customer.updated", "description": "Cliente atualizado" },
    { "code": "recipient.created", "description": "Recebedor criado" },
    { "code": "recipient.updated", "description": "Recebedor atualizado" },
    { "code": "recipient.approved", "description": "Recebedor aprovado" },
    { "code": "recipient.refused", "description": "Recebedor recusado" },
    { "code": "recipient.deleted", "description": "Recebedor removido" },
    { "code": "withdrawal.requested", "description": "Saque solicitado" },
    { "code": "withdrawal.paid", "description": "Saque pago" },
    { "code": "withdrawal.rejected", "description": "Saque recusado" },
    { "code": "invoice.issued", "description": "Fatura emitida" },
    { "code": "invoice.payment_attempted", "description": "Tentativa de cobrança da fatura" },
    { "code": "invoice.paid", "description": "Fatura paga" },
    { "code": "invoice.voided", "description": "Fatura anulada" },
    { "code": "invoice.refunded", "description": "Fatura reembolsada" },
    { "code": "invoice.rescheduled", "description": "Fatura reagendada" },
    { "code": "subscription.created", "description": "Assinatura criada" },
    { "code": "subscription.activated", "description": "Assinatura ativada" },
    { "code": "subscription.canceled", "description": "Assinatura cancelada" },
    { "code": "subscription.cycle_advanced", "description": "Novo ciclo da assinatura iniciado" },
    { "code": "subscription.paused", "description": "Assinatura pausada" },
    { "code": "subscription.resumed", "description": "Assinatura retomada" }
  ]
}
Os códigos seguem o padrão recurso.acao (ex: transaction.paid). A documentação detalhada de cada payload por evento está em Catálogo de eventos.

​
Buscar webhook por ID

GET /webhooks/:id Retorna os dados de um webhook específico.
StatusQuando
200Webhook encontrado.
404Webhook não encontrado. Veja Erros.
curl -X GET https://api.sandbox.z2pay.com/webhooks/whk_8Hk2pQ7rT9vLm3Nx \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "whk_8Hk2pQ7rT9vLm3Nx",
  "companyId": "comp_4Zp1Yt6Bn0Wq",
  "name": "Notificações de pagamento",
  "url": "https://meusite.com/webhooks/z2pay",
  "events": ["transaction.paid", "transaction.refunded"],
  "secret": "um-segredo-bem-grande",
  "isActive": true,
  "createdAt": "2026-06-24T13:45:00.000Z",
  "updatedAt": "2026-06-24T13:45:00.000Z",
  "deletedAt": null,
  "version": 1
}

​
Atualizar webhook

PUT /webhooks/:id Atualiza as configurações de um webhook. Todos os campos do corpo são opcionais — envie apenas o que deseja mudar. Retorna 200 com o webhook atualizado.
​
name
string
Novo nome. Entre 1 e 255 caracteres.
​
url
string
Nova URL HTTPS pública. URLs internas/privadas são rejeitadas.
​
events
string[]
Nova lista de eventos a assinar. Se enviada vazia, o webhook passa a escutar TODOS os eventos.
​
secret
string
Novo segredo. Mínimo de 8 caracteres.
Este endpoint aceita o header Idempotency-Key.
StatusQuando
200Webhook atualizado.
404Webhook não encontrado.
curl -X PUT https://api.sandbox.z2pay.com/webhooks/whk_8Hk2pQ7rT9vLm3Nx \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["transaction.paid", "transaction.refused", "transaction.refunded"]
  }'

{
  "id": "whk_8Hk2pQ7rT9vLm3Nx",
  "companyId": "comp_4Zp1Yt6Bn0Wq",
  "name": "Notificações de pagamento",
  "url": "https://meusite.com/webhooks/z2pay",
  "events": ["transaction.paid", "transaction.refused", "transaction.refunded"],
  "secret": "um-segredo-bem-grande",
  "isActive": true,
  "createdAt": "2026-06-24T13:45:00.000Z",
  "updatedAt": "2026-06-24T14:10:00.000Z",
  "deletedAt": null,
  "version": 2
}

​
Ativar / desativar webhook

PATCH /webhooks/:id/status Altera o status ativo/inativo de um webhook. Um webhook inativo não recebe novas entregas. Retorna 200.
​
isActive
boolean
obrigatório
true para ativar, false para desativar.
Este endpoint aceita o header Idempotency-Key.
StatusQuando
200Status atualizado.
404Webhook não encontrado.
curl -X PATCH https://api.sandbox.z2pay.com/webhooks/whk_8Hk2pQ7rT9vLm3Nx/status \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

{
  "id": "whk_8Hk2pQ7rT9vLm3Nx",
  "companyId": "comp_4Zp1Yt6Bn0Wq",
  "name": "Notificações de pagamento",
  "url": "https://meusite.com/webhooks/z2pay",
  "events": ["transaction.paid", "transaction.refunded"],
  "secret": "um-segredo-bem-grande",
  "isActive": false,
  "createdAt": "2026-06-24T13:45:00.000Z",
  "updatedAt": "2026-06-24T14:20:00.000Z",
  "deletedAt": null,
  "version": 3
}

​
Remover webhook

DELETE /webhooks/:id Remove um webhook usando soft delete: a entidade não é apagada, apenas marcada com deletedAt preenchido. Retorna 200 com a entidade removida. Este endpoint aceita o header Idempotency-Key.
StatusQuando
200Webhook removido.
404Webhook não encontrado.
curl -X DELETE https://api.sandbox.z2pay.com/webhooks/whk_8Hk2pQ7rT9vLm3Nx \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "whk_8Hk2pQ7rT9vLm3Nx",
  "companyId": "comp_4Zp1Yt6Bn0Wq",
  "name": "Notificações de pagamento",
  "url": "https://meusite.com/webhooks/z2pay",
  "events": ["transaction.paid", "transaction.refunded"],
  "secret": "um-segredo-bem-grande",
  "isActive": false,
  "createdAt": "2026-06-24T13:45:00.000Z",
  "updatedAt": "2026-06-24T14:25:00.000Z",
  "deletedAt": "2026-06-24T14:25:00.000Z",
  "version": 4
}

​
Listar entregas (deliveries)

GET /webhooks/deliveries Retorna uma lista paginada das tentativas de entrega de webhooks. Cada delivery é o registro de uma notificação enviada (ou que está em processo de envio) para a sua URL.
Parâmetro (query)TipoObrigatórioDescrição
webhookIdstringNãoFiltra pelas entregas de um webhook específico.
eventTypestringNãoFiltra por tipo de evento (ex: transaction.paid).
statusstringNãoFiltra por status. Valores: pending, success, failed, retrying.
fromstring (ISO 8601)NãoData inicial do intervalo de criação.
tostring (ISO 8601)NãoData final do intervalo de criação.
sortstringNãoOrdenação. Valores: createdAt.asc, createdAt.desc. Padrão createdAt.desc.
pageintegerNãoPágina (inteiro positivo). Padrão 1.
limitintegerNãoItens por página (inteiro positivo, máximo 100). Padrão 20.
curl -X GET "https://api.sandbox.z2pay.com/webhooks/deliveries?status=failed&page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "whd_5Qm9Rt2pK7vBn1Xz",
      "companyId": "comp_4Zp1Yt6Bn0Wq",
      "webhookId": "whk_8Hk2pQ7rT9vLm3Nx",
      "eventId": "evt_1a2b3c4d5e6f",
      "eventType": "transaction.paid",
      "entityType": "transaction",
      "entityId": "txn_9Lp3Kt7rQ2vMn4Xz",
      "url": "https://meusite.com/webhooks/z2pay",
      "payload": {
        "event": "transaction.paid",
        "data": { "id": "txn_9Lp3Kt7rQ2vMn4Xz" }
      },
      "status": "failed",
      "attemptCount": 3,
      "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
  }
}

​
Buscar entrega por ID

GET /webhooks/deliveries/:id Retorna os dados completos de uma entrega, incluindo o payload enviado e o returnData da resposta recebida — útil para depurar uma entrega que falhou.
StatusQuando
200Entrega encontrada.
404Entrega não encontrada.
​
id
string
ID da entrega (prefixo whd_).
​
webhookId
string
ID do webhook que originou esta entrega.
​
eventId
string | null
ID do evento que disparou a entrega.
​
eventType
string
Tipo do evento (ex: transaction.paid).
​
entityType
string | null
Tipo da entidade relacionada (ex: transaction).
​
entityId
string | null
ID da entidade relacionada (ex: txn_...).
​
url
string
URL para a qual a entrega foi enviada.
​
payload
object
Conteúdo JSON enviado na entrega.
​
status
string
Status da entrega: pending, success, failed ou retrying.
​
attemptCount
integer
Número de tentativas de envio já realizadas.
​
returnStatus
integer | null
Código HTTP retornado pelo seu endpoint na última tentativa.
​
returnData
object | null
Corpo da resposta retornado pelo seu endpoint.
​
errorMessage
string | null
Mensagem de erro da última tentativa, quando houver.
​
lastAttemptAt
string | null
Data/hora da última tentativa (ISO 8601), quando houver.
​
createdAt
string
Data/hora de criação da entrega (ISO 8601).
​
updatedAt
string
Data/hora da última atualização (ISO 8601).
curl -X GET https://api.sandbox.z2pay.com/webhooks/deliveries/whd_5Qm9Rt2pK7vBn1Xz \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "whd_5Qm9Rt2pK7vBn1Xz",
  "companyId": "comp_4Zp1Yt6Bn0Wq",
  "webhookId": "whk_8Hk2pQ7rT9vLm3Nx",
  "eventId": "evt_1a2b3c4d5e6f",
  "eventType": "transaction.paid",
  "entityType": "transaction",
  "entityId": "txn_9Lp3Kt7rQ2vMn4Xz",
  "url": "https://meusite.com/webhooks/z2pay",
  "payload": {
    "event": "transaction.paid",
    "data": { "id": "txn_9Lp3Kt7rQ2vMn4Xz" }
  },
  "status": "failed",
  "attemptCount": 3,
  "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"
}

​
Reprocessar entrega

POST /webhooks/deliveries/:id/retry Reenvia uma entrega que falhou anteriormente. Use após corrigir o seu endpoint para receber novamente a notificação. Retorna 200 com { "ok": true }. Este endpoint aceita o header Idempotency-Key.
StatusQuando
200Entrega reenviada (enfileirada para reprocessamento).
404Entrega não encontrada.
curl -X POST https://api.sandbox.z2pay.com/webhooks/deliveries/whd_5Qm9Rt2pK7vBn1Xz/retry \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "ok": true
}
Tratamento de erros (formato do corpo, status codes comuns como 400 de validação e 401 de autenticação) está documentado em Erros.

​
Veja também

Webhooks: visão geral

Como funciona a entrega, retentativas e validação de assinatura.

Catálogo de eventos

Cada evento e o payload que você recebe.

Transações

A origem da maioria dos eventos de webhook.

Erros

Formato de erro e status codes da API.