Skip to main content
Webhooks notify your system in real time whenever something happens on Z2Pay (a transaction was paid, a withdrawal was rejected, an invoice was issued, etc.). This page covers webhook management (CRUD) and delivery history (deliveries).
To understand event signature concepts, payload format, and how to validate incoming signatures, see Webhooks: overview and Event catalog.
All requests require the x-api-key header. See Authentication.

​
Endpoints

​
Webhook configuration

MethodRouteDescription
POST/webhooksCreate a webhook
GET/webhooksList webhooks (paginated)
GET/webhooks/listenersList the available event catalog
GET/webhooks/:idFetch a webhook by ID
PUT/webhooks/:idUpdate a webhook
PATCH/webhooks/:id/statusEnable or disable a webhook
DELETE/webhooks/:idRemove a webhook (soft delete)

​
Delivery history

MethodRouteDescription
GET/webhooks/deliveriesList deliveries (paginated, with filters)
GET/webhooks/deliveries/:idFetch a delivery by ID
POST/webhooks/deliveries/:id/retryRetry a delivery
The webhook URL must use HTTPS and point to a public host. URLs that resolve to localhost, private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local/cloud metadata addresses (169.254.0.0/16, metadata.google.internal), or schemes other than http/https are rejected with 400. This protects against SSRF attacks.

​
Create webhook

POST /webhooks Registers a new webhook. Returns 201 with the created webhook.
​
name
string
required
Identifying name for the webhook. Between 1 and 255 characters.
​
url
string
required
Public HTTPS URL that will receive the notifications. Internal/private URLs are rejected (see the warning above).
​
events
string[]
default:"[]"
List of events to subscribe to. Each value must be a code from the event catalog. If sent empty (or omitted), the webhook listens to ALL events.
​
secret
string
Secret used to sign the delivery payload. Minimum 8 characters. Optional. See signature validation.
This endpoint accepts the Idempotency-Key header to prevent duplicate creations. See Conventions. 
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
}

​
List webhooks

GET /webhooks Returns a paginated list of webhooks on your account.
Parameter (query)TypeRequiredDescription
isActivebooleanNoFilter by active/inactive status.
eventstringNoFilter webhooks listening to a specific event (e.g. transaction.paid).
pageintegerNoPage number (positive integer). Default 1.
limitintegerNoItems per page (positive integer, maximum 100). Default 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
  }
}

​
List available events

GET /webhooks/listeners Returns the full catalog of events available for subscription. Use the code values in the events field when creating or updating a webhook. Accepts no parameters. 
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" }
  ]
}
Codes follow the resource.action pattern (e.g. transaction.paid). Detailed payload documentation for each event is available in the Event catalog.

​
Fetch webhook by ID

GET /webhooks/:id Returns the data for a specific webhook.
StatusWhen
200Webhook found.
404Webhook not found. See Errors.
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
}

​
Update webhook

PUT /webhooks/:id Updates the configuration of a webhook. All body fields are optional — only send what you want to change. Returns 200 with the updated webhook.
​
name
string
New name. Between 1 and 255 characters.
​
url
string
New public HTTPS URL. Internal/private URLs are rejected.
​
events
string[]
New list of events to subscribe to. If sent empty, the webhook will listen to ALL events.
​
secret
string
New secret. Minimum 8 characters.
This endpoint accepts the Idempotency-Key header.
StatusWhen
200Webhook updated.
404Webhook not found.
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
}

​
Enable / disable webhook

PATCH /webhooks/:id/status Toggles the active/inactive status of a webhook. An inactive webhook does not receive new deliveries. Returns 200.
​
isActive
boolean
required
true to enable, false to disable.
This endpoint accepts the Idempotency-Key header.
StatusWhen
200Status updated.
404Webhook not found.
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
}

​
Remove webhook

DELETE /webhooks/:id Removes a webhook using soft delete: the entity is not permanently erased, it is simply marked with a populated deletedAt timestamp. Returns 200 with the removed entity. This endpoint accepts the Idempotency-Key header.
StatusWhen
200Webhook removed.
404Webhook not found.
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
}

​
List deliveries

GET /webhooks/deliveries Returns a paginated list of webhook delivery attempts. Each delivery is a record of a notification sent (or in the process of being sent) to your URL.
Parameter (query)TypeRequiredDescription
webhookIdstringNoFilter by deliveries for a specific webhook.
eventTypestringNoFilter by event type (e.g. transaction.paid).
statusstringNoFilter by status. Values: pending, success, failed, retrying.
fromstring (ISO 8601)NoStart date of the creation range.
tostring (ISO 8601)NoEnd date of the creation range.
sortstringNoSort order. Values: createdAt.asc, createdAt.desc. Default createdAt.desc.
pageintegerNoPage number (positive integer). Default 1.
limitintegerNoItems per page (positive integer, maximum 100). Default 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
  }
}

​
Fetch delivery by ID

GET /webhooks/deliveries/:id Returns the full data for a delivery, including the payload sent and the returnData from the response received — useful for debugging a failed delivery.
StatusWhen
200Delivery found.
404Delivery not found.
​
id
string
Delivery ID (prefix whd_).
​
webhookId
string
ID of the webhook that originated this delivery.
​
eventId
string | null
ID of the event that triggered the delivery.
​
eventType
string
Event type (e.g. transaction.paid).
​
entityType
string | null
Type of the related entity (e.g. transaction).
​
entityId
string | null
ID of the related entity (e.g. txn_...).
​
url
string
URL to which the delivery was sent.
​
payload
object
JSON content sent in the delivery.
​
status
string
Delivery status: pending, success, failed, or retrying.
​
attemptCount
integer
Number of send attempts already made.
​
returnStatus
integer | null
HTTP status code returned by your endpoint on the last attempt.
​
returnData
object | null
Response body returned by your endpoint.
​
errorMessage
string | null
Error message from the last attempt, if any.
​
lastAttemptAt
string | null
Date/time of the last attempt (ISO 8601), if any.
​
createdAt
string
Date/time the delivery was created (ISO 8601).
​
updatedAt
string
Date/time of the last update (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"
}

​
Retry delivery

POST /webhooks/deliveries/:id/retry Resends a previously failed delivery. Use this after fixing your endpoint to receive the notification again. Returns 200 with { "ok": true }. This endpoint accepts the Idempotency-Key header.
StatusWhen
200Delivery resent (queued for reprocessing).
404Delivery not found.
curl -X POST https://api.sandbox.z2pay.com/webhooks/deliveries/whd_5Qm9Rt2pK7vBn1Xz/retry \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "ok": true
}
Error handling (body format, common status codes such as 400 for validation and 401 for authentication) is documented in Errors.

​
See also

Webhooks: overview

How delivery works, retry logic, and signature validation.

Event catalog

Every event and the payload you receive.

Transactions

The source of most webhook events.

Errors

Error format and API status codes.