Pular para o conteúdo principal
Toda notificação de webhook carrega um campo type com o código do evento (ex: transaction.paid). Ao cadastrar um webhook, você escolhe quais códigos deseja receber — ou deixa a lista de eventos vazia para receber todos. Esta página lista todos os eventos disponíveis no catálogo oficial. O mesmo catálogo é exposto pela API em GET /webhooks/listeners, então você pode buscá-lo programaticamente em vez de copiar daqui.
Códigos de evento são case-sensitive e seguem o padrão recurso.acao em minúsculas com _ para separar palavras (ex: subscription.cycle_advanced). Use exatamente os valores desta página ao preencher o array events na criação do webhook.

​
Estrutura de uma notificação

Independente do evento, o corpo entregue ao seu endpoint tem sempre o mesmo envelope. O objeto da entidade que disparou o evento fica em data.
​
id
string
Identificador da entrega (delivery), com prefixo whd_. Útil para deduplicação no seu lado.
​
type
string
Código do evento (ex: transaction.paid). É um dos valores desta página.
​
data
object
Objeto da entidade relacionada ao evento (a transação, o pagamento, a fatura, etc.).
​
occurredAt
string
Data/hora em que o evento ocorreu, em ISO 8601 com timezone (UTC).
​
companyId
string
Identificador da sua conta (company) que originou o evento.
{
  "id": "whd_3f9a2c7b8e1d4a06",
  "type": "transaction.paid",
  "data": {
    "id": "txn_8d2e1f0a9c4b7e63",
    "status": "paid",
    "amount": 19990,
    "companyId": "comp_0a1b2c3d4e5f6789"
  },
  "occurredAt": "2026-06-24T13:45:10.812Z",
  "companyId": "comp_0a1b2c3d4e5f6789"
}
Se você cadastrou um secret no webhook, cada requisição vem com o header X-Webhook-Signature contendo HMAC-SHA256(secret, JSON.stringify(body)) em hexadecimal. Veja como validar em Webhooks · Visão geral.

​
Eventos por recurso

​
Transação (transaction.*)

Eventos do ciclo de vida de uma transação. O campo data traz o objeto da transação (prefixo txn_).
CódigoDescrição
transaction.createdTransação criada
transaction.waiting_paymentTransação aguardando pagamento
transaction.paidTransação paga
transaction.refusedTransação recusada
transaction.failedTransação falhou
transaction.canceledTransação cancelada
transaction.refundedTransação reembolsada
transaction.chargebackTransação em chargeback

​
Pagamento (payment.*)

Eventos do ciclo de vida de um pagamento. O campo data traz o objeto do pagamento (prefixo pay_).
CódigoDescrição
payment.createdPagamento criado
payment.waiting_paymentPagamento aguardando pagamento
payment.paidPagamento aprovado
payment.refusedPagamento recusado
payment.failedPagamento falhou
payment.refundedPagamento reembolsado
payment.chargebackPagamento em chargeback

​
Cliente (customer.*)

Eventos de cadastro de clientes. O campo data traz o objeto do cliente (prefixo cust_).
CódigoDescrição
customer.createdCliente criado
customer.updatedCliente atualizado

​
Recebedor (recipient.*)

Eventos do ciclo de vida do vínculo de um recebedor com a sua conta. O campo data traz os dados cadastrais do recebedor (prefixo rec_), no mesmo formato de GET /recipients/:id.
CódigoDescrição
recipient.createdRecebedor criado
recipient.updatedRecebedor atualizado
recipient.approvedRecebedor aprovado
recipient.refusedRecebedor recusado
recipient.deletedRecebedor removido

​
Saque (withdrawal.*)

Eventos de saque da carteira (wallet). O campo data traz o objeto do saque.
CódigoDescrição
withdrawal.requestedSaque solicitado
withdrawal.paidSaque pago
withdrawal.rejectedSaque recusado

​
Fatura (invoice.*)

Eventos do ciclo de vida de faturas geradas pelo motor de cobrança (billing). O campo data traz o objeto da fatura (prefixo inv_).
CódigoDescrição
invoice.issuedFatura emitida
invoice.payment_attemptedTentativa de cobrança da fatura
invoice.paidFatura paga
invoice.voidedFatura anulada
invoice.refundedFatura reembolsada
invoice.rescheduledFatura reagendada
No evento invoice.payment_attempted, o data carrega o resultado da tentativa de cobrança (e o invoiceId referenciado), não o objeto completo da fatura.

​
Assinatura (subscription.*)

Eventos do ciclo de vida de assinaturas do motor de cobrança (billing). O campo data traz o objeto da assinatura (prefixo sub_).
CódigoDescrição
subscription.createdAssinatura criada
subscription.activatedAssinatura ativada
subscription.canceledAssinatura cancelada
subscription.cycle_advancedNovo ciclo da assinatura iniciado
subscription.pausedAssinatura pausada
subscription.resumedAssinatura retomada

​
Buscar o catálogo pela API

Você pode obter a mesma lista (código + descrição) dinamicamente. O endpoint exige autenticação por API key.
​
GET /webhooks/listeners
endpoint
curl 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.paid", "description": "Transação paga" },
    { "code": "subscription.cycle_advanced", "description": "Novo ciclo da assinatura iniciado" }
  ]
}
Passe os códigos desejados no array events. Um array vazio ([]) faz o webhook receber todos os eventos.
curl -X POST https://api.sandbox.z2pay.com/webhooks \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Notificações de pagamento",
    "url": "https://meusite.com/webhooks/z2pay",
    "events": ["transaction.paid", "transaction.refused", "subscription.cycle_advanced"],
    "secret": "um-segredo-com-no-minimo-8-chars"
  }'
Detalhes de criação, atualização e validação de assinatura ficam em Webhooks · Visão geral.

​
Veja também

Webhooks · Visão geral

Como cadastrar webhooks, validar assinatura e reprocessar entregas.

Transações

O objeto transaction enviado nos eventos transaction.*.

Pagamentos

O objeto payment enviado nos eventos payment.*.

Assinaturas

Faturas e assinaturas que disparam os eventos invoice.* e subscription.*.