Webhooks (gestión) - Z2Pay Developers

Los webhooks notifican a tu sistema en tiempo real cuando algo ocurre en Z2Pay (una transacción fue pagada, un retiro fue rechazado, una factura fue emitida, etc.). Esta página cubre la gestión de webhooks (CRUD) y el historial de entregas (deliveries).

Para entender el concepto de firma de eventos, el formato del payload y cómo validar la firma recibida, consulta Webhooks: descripción general y Catálogo de eventos.

Todas las solicitudes requieren el header x-api-key. Consulta Autenticación.

Endpoints

Configuración de webhooks

Método	Ruta	Descripción
`POST`	`/webhooks`	Crear un webhook
`GET`	`/webhooks`	Listar webhooks (paginado)
`GET`	`/webhooks/listeners`	Listar el catálogo de eventos disponibles
`GET`	`/webhooks/:id`	Buscar un webhook por ID
`PUT`	`/webhooks/:id`	Actualizar un webhook
`PATCH`	`/webhooks/:id/status`	Activar o desactivar un webhook
`DELETE`	`/webhooks/:id`	Eliminar un webhook (soft delete)

Historial de entregas (deliveries)

Método	Ruta	Descripción
`GET`	`/webhooks/deliveries`	Listar entregas (paginado, con filtros)
`GET`	`/webhooks/deliveries/:id`	Buscar una entrega por ID
`POST`	`/webhooks/deliveries/:id/retry`	Reprocesar una entrega

La URL del webhook debe usar HTTPS y apuntar a un host público. Las URLs que resuelven a localhost, rangos 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) o esquemas distintos de http/https son rechazadas con 400. Esto protege contra SSRF.

Crear webhook

POST /webhooks Registra un nuevo webhook. Devuelve 201 con el webhook creado.

name

string

requerido

Nombre de identificación del webhook. Entre 1 y 255 caracteres.

url

string

requerido

URL HTTPS pública que recibirá las notificaciones. Las URLs internas/privadas son rechazadas (consulta la advertencia anterior).

events

string[]

predeterminado:"[]"

Lista de eventos a suscribir. Cada valor debe ser un código del catálogo de eventos. Si se envía vacío (u omitido), el webhook escucha TODOS los eventos.

secret

string

Secreto usado para firmar el payload de las entregas. Mínimo de 8 caracteres. Opcional. Consulta validación de firma.

Este endpoint acepta el header Idempotency-Key para evitar creaciones duplicadas. Consulta Convenciones.

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 Devuelve una lista paginada de los webhooks de tu cuenta.

Parámetro (query)	Tipo	Obligatorio	Descripción
`isActive`	`boolean`	No	Filtra por estado activo/inactivo.
`event`	`string`	No	Filtra webhooks que escuchan un evento específico (ej: `transaction.paid`).
`page`	`integer`	No	Página (entero positivo). Por defecto `1`.
`limit`	`integer`	No	Elementos por página (entero positivo, máximo `100`). Por defecto `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 disponibles

GET /webhooks/listeners Devuelve el catálogo completo de eventos que pueden ser suscritos. Usa los valores de code en el campo events al crear o actualizar un webhook. No acepta 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" }
  ]
}

Los códigos siguen el patrón recurso.accion (ej: transaction.paid). La documentación detallada de cada payload por evento está en Catálogo de eventos.

Buscar webhook por ID

GET /webhooks/:id Devuelve los datos de un webhook específico.

Estado	Cuándo
`200`	Webhook encontrado.
`404`	Webhook no encontrado. Consulta Errores.

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
}

Actualizar webhook

PUT /webhooks/:id Actualiza la configuración de un webhook. Todos los campos del cuerpo son opcionales — envía solo lo que deseas cambiar. Devuelve 200 con el webhook actualizado.

name

string

Nuevo nombre. Entre 1 y 255 caracteres.

url

string

Nueva URL HTTPS pública. Las URLs internas/privadas son rechazadas.

events

string[]

Nueva lista de eventos a suscribir. Si se envía vacía, el webhook pasará a escuchar TODOS los eventos.

secret

string

Nuevo secreto. Mínimo de 8 caracteres.

Este endpoint acepta el header Idempotency-Key.

Estado	Cuándo
`200`	Webhook actualizado.
`404`	Webhook no 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
}

Activar / desactivar webhook

PATCH /webhooks/:id/status Cambia el estado activo/inactivo de un webhook. Un webhook inactivo no recibe nuevas entregas. Devuelve 200.

isActive

boolean

requerido

true para activar, false para desactivar.

Este endpoint acepta el header Idempotency-Key.

Estado	Cuándo
`200`	Estado actualizado.
`404`	Webhook no 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
}

Eliminar webhook

DELETE /webhooks/:id Elimina un webhook mediante soft delete: la entidad no se borra, solo se marca con deletedAt completado. Devuelve 200 con la entidad eliminada. Este endpoint acepta el header Idempotency-Key.

Estado	Cuándo
`200`	Webhook eliminado.
`404`	Webhook no 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 Devuelve una lista paginada de los intentos de entrega de webhooks. Cada delivery es el registro de una notificación enviada (o en proceso de envío) hacia tu URL.

Parámetro (query)	Tipo	Obligatorio	Descripción
`webhookId`	`string`	No	Filtra las entregas de un webhook específico.
`eventType`	`string`	No	Filtra por tipo de evento (ej: `transaction.paid`).
`status`	`string`	No	Filtra por estado. Valores: `pending`, `success`, `failed`, `retrying`.
`from`	`string` (ISO 8601)	No	Fecha inicial del intervalo de creación.
`to`	`string` (ISO 8601)	No	Fecha final del intervalo de creación.
`sort`	`string`	No	Ordenación. Valores: `createdAt.asc`, `createdAt.desc`. Por defecto `createdAt.desc`.
`page`	`integer`	No	Página (entero positivo). Por defecto `1`.
`limit`	`integer`	No	Elementos por página (entero positivo, máximo `100`). Por defecto `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 Devuelve los datos completos de una entrega, incluyendo el payload enviado y el returnData de la respuesta recibida — útil para depurar una entrega fallida.

Estado	Cuándo
`200`	Entrega encontrada.
`404`	Entrega no encontrada.

string

ID de la entrega (prefijo whd_).

webhookId

string

ID del webhook que originó esta entrega.

eventId

string | null

ID del evento que disparó la entrega.

eventType

string

Tipo del evento (ej: transaction.paid).

entityType

string | null

Tipo de la entidad relacionada (ej: transaction).

entityId

string | null

ID de la entidad relacionada (ej: txn_...).

url

string

URL a la que se envió la entrega.

payload

object

Contenido JSON enviado en la entrega.

status

string

Estado de la entrega: pending, success, failed o retrying.

attemptCount

integer

Número de intentos de envío ya realizados.

returnStatus

integer | null

Código HTTP devuelto por tu endpoint en el último intento.

returnData

object | null

Cuerpo de la respuesta devuelto por tu endpoint.

errorMessage

string | null

Mensaje de error del último intento, cuando lo haya.

lastAttemptAt

string | null

Fecha/hora del último intento (ISO 8601), cuando lo haya.

createdAt

string

Fecha/hora de creación de la entrega (ISO 8601).

updatedAt

string

Fecha/hora de la última actualización (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"
}

Reprocesar entrega

POST /webhooks/deliveries/:id/retry Reenvía una entrega que falló anteriormente. Úsalo después de corregir tu endpoint para volver a recibir la notificación. Devuelve 200 con { "ok": true }. Este endpoint acepta el header Idempotency-Key.

Estado	Cuándo
`200`	Entrega reenviada (encolada para reprocesamiento).
`404`	Entrega no encontrada.

curl -X POST https://api.sandbox.z2pay.com/webhooks/deliveries/whd_5Qm9Rt2pK7vBn1Xz/retry \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "ok": true
}

El manejo de errores (formato del cuerpo, status codes comunes como 400 de validación y 401 de autenticación) está documentado en Errores.

Ver también

Webhooks: descripción general

Cómo funciona la entrega, los reintentos y la validación de firma.

Catálogo de eventos

Cada evento y el payload que recibes.

Transacciones

El origen de la mayoría de los eventos de webhook.

Errores

Formato de error y status codes de la API.

​Endpoints

​Configuración de webhooks

​Historial de entregas (deliveries)

​Crear webhook

​Listar webhooks

​Listar eventos disponibles

​Buscar webhook por ID

​Actualizar webhook

​Activar / desactivar webhook

​Eliminar webhook

​Listar entregas (deliveries)

​Buscar entrega por ID

​Reprocesar entrega

​Ver también

Webhooks: descripción general

Catálogo de eventos

Transacciones

Errores

Endpoints

Configuración de webhooks

Historial de entregas (deliveries)

Crear webhook

Listar webhooks

Listar eventos disponibles

Buscar webhook por ID

Actualizar webhook

Activar / desactivar webhook

Eliminar webhook

Listar entregas (deliveries)

Buscar entrega por ID

Reprocesar entrega

Ver también