Saltar al contenido principal
Toda notificación de webhook incluye un campo type con el código del evento (ej.: transaction.paid). Al registrar un webhook, eliges qué códigos deseas recibir — o dejas la lista de eventos vacía para recibir todos. Esta página lista todos los eventos disponibles en el catálogo oficial. El mismo catálogo está expuesto por la API en GET /webhooks/listeners, por lo que puedes consultarlo programáticamente en lugar de copiarlo desde aquí.
Los códigos de evento son case-sensitive y siguen el patrón recurso.accion en minúsculas con _ para separar palabras (ej.: subscription.cycle_advanced). Usa exactamente los valores de esta página al completar el array events en la creación del webhook.

​
Estructura de una notificación

Independientemente del evento, el cuerpo entregado a tu endpoint siempre tiene el mismo envoltorio. El objeto de la entidad que disparó el evento se encuentra en data.
​
id
string
Identificador de la entrega (delivery), con prefijo whd_. Útil para la deduplicación en tu lado.
​
type
string
Código del evento (ej.: transaction.paid). Es uno de los valores de esta página.
​
data
object
Objeto de la entidad relacionada con el evento (la transacción, el pago, la factura, etc.).
​
occurredAt
string
Fecha/hora en que ocurrió el evento, en ISO 8601 con timezone (UTC).
​
companyId
string
Identificador de tu cuenta (company) que originó el 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"
}
Si registraste un secret en el webhook, cada solicitud incluye el header X-Webhook-Signature con HMAC-SHA256(secret, JSON.stringify(body)) en hexadecimal. Consulta cómo validarlo en Webhooks · Visión general.

​
Eventos por recurso

​
Transacción (transaction.*)

Eventos del ciclo de vida de una transacción. El campo data contiene el objeto de la transacción (prefijo txn_).
CódigoDescripción
transaction.createdTransacción creada
transaction.waiting_paymentTransacción en espera de pago
transaction.paidTransacción pagada
transaction.refusedTransacción rechazada
transaction.failedTransacción fallida
transaction.canceledTransacción cancelada
transaction.refundedTransacción reembolsada
transaction.chargebackTransacción en contracargo

​
Pago (payment.*)

Eventos del ciclo de vida de un pago. El campo data contiene el objeto del pago (prefijo pay_).
CódigoDescripción
payment.createdPago creado
payment.waiting_paymentPago en espera de pago
payment.paidPago aprobado
payment.refusedPago rechazado
payment.failedPago fallido
payment.refundedPago reembolsado
payment.chargebackPago en contracargo

​
Cliente (customer.*)

Eventos de registro de clientes. El campo data contiene el objeto del cliente (prefijo cust_).
CódigoDescripción
customer.createdCliente creado
customer.updatedCliente actualizado

​
Beneficiario (recipient.*)

Eventos del ciclo de vida del vínculo de un beneficiario con tu cuenta. El campo data contiene los datos de registro del beneficiario (prefijo rec_), en el mismo formato que GET /recipients/:id.
CódigoDescripción
recipient.createdBeneficiario creado
recipient.updatedBeneficiario actualizado
recipient.approvedBeneficiario aprobado
recipient.refusedBeneficiario rechazado
recipient.deletedBeneficiario eliminado

​
Retiro (withdrawal.*)

Eventos de retiro de la billetera (wallet). El campo data contiene el objeto del retiro.
CódigoDescripción
withdrawal.requestedRetiro solicitado
withdrawal.paidRetiro pagado
withdrawal.rejectedRetiro rechazado

​
Factura (invoice.*)

Eventos del ciclo de vida de facturas generadas por el motor de cobros (billing). El campo data contiene el objeto de la factura (prefijo inv_).
CódigoDescripción
invoice.issuedFactura emitida
invoice.payment_attemptedIntento de cobro de la factura
invoice.paidFactura pagada
invoice.voidedFactura anulada
invoice.refundedFactura reembolsada
invoice.rescheduledFactura reprogramada
En el evento invoice.payment_attempted, el data contiene el resultado del intento de cobro (y el invoiceId referenciado), no el objeto completo de la factura.

​
Suscripción (subscription.*)

Eventos del ciclo de vida de suscripciones del motor de cobros (billing). El campo data contiene el objeto de la suscripción (prefijo sub_).
CódigoDescripción
subscription.createdSuscripción creada
subscription.activatedSuscripción activada
subscription.canceledSuscripción cancelada
subscription.cycle_advancedNuevo ciclo de suscripción iniciado
subscription.pausedSuscripción pausada
subscription.resumedSuscripción reanudada

​
Consultar el catálogo por la API

Puedes obtener la misma lista (código + descripción) de forma dinámica. El endpoint requiere autenticación mediante 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" }
  ]
}
Pasa los códigos deseados en el array events. Un array vacío ([]) hace que el webhook reciba todos los 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"
  }'
Los detalles de creación, actualización y validación de firma están en Webhooks · Visión general.

​
Ver también

Webhooks · Visión general

Cómo registrar webhooks, validar la firma y reprocesar entregas.

Transacciones

El objeto transaction enviado en los eventos transaction.*.

Pagos

El objeto payment enviado en los eventos payment.*.

Suscripciones

Facturas y suscripciones que disparan los eventos invoice.* y subscription.*.