Skip to main content
Every webhook notification includes a type field with the event code (e.g. transaction.paid). When registering a webhook, you choose which codes you want to receive — or leave the events list empty to receive all of them. This page lists every event available in the official catalog. The same catalog is exposed by the API at GET /webhooks/listeners, so you can fetch it programmatically instead of copying it from here.
Event codes are case-sensitive and follow the resource.action pattern in lowercase with _ to separate words (e.g. subscription.cycle_advanced). Use exactly the values from this page when filling in the events array when creating a webhook.

​
Notification structure

Regardless of the event, the body delivered to your endpoint always has the same envelope. The object of the entity that triggered the event is located in data.
​
id
string
Delivery identifier, with the whd_ prefix. Useful for deduplication on your end.
​
type
string
Event code (e.g. transaction.paid). It is one of the values listed on this page.
​
data
object
The entity object related to the event (the transaction, payment, invoice, etc.).
​
occurredAt
string
Date/time the event occurred, in ISO 8601 format with timezone (UTC).
​
companyId
string
Identifier of your account (company) that originated the event.
{
  "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"
}
If you registered a secret on the webhook, each request includes the X-Webhook-Signature header containing HMAC-SHA256(secret, JSON.stringify(body)) in hexadecimal. See how to validate it in Webhooks · Overview.

​
Events by resource

​
Transaction (transaction.*)

Events for the lifecycle of a transaction. The data field contains the transaction object (prefix txn_).
CodeDescription
transaction.createdTransaction created
transaction.waiting_paymentTransaction waiting for payment
transaction.paidTransaction paid
transaction.refusedTransaction refused
transaction.failedTransaction failed
transaction.canceledTransaction canceled
transaction.refundedTransaction refunded
transaction.chargebackTransaction under chargeback

​
Payment (payment.*)

Events for the lifecycle of a payment. The data field contains the payment object (prefix pay_).
CodeDescription
payment.createdPayment created
payment.waiting_paymentPayment waiting for payment
payment.paidPayment approved
payment.refusedPayment refused
payment.failedPayment failed
payment.refundedPayment refunded
payment.chargebackPayment under chargeback

​
Customer (customer.*)

Events for customer registration. The data field contains the customer object (prefix cust_).
CodeDescription
customer.createdCustomer created
customer.updatedCustomer updated

​
Recipient (recipient.*)

Events for the lifecycle of a recipient’s association with your account. The data field contains the recipient’s registration data (prefix rec_), in the same format as GET /recipients/:id.
CodeDescription
recipient.createdRecipient created
recipient.updatedRecipient updated
recipient.approvedRecipient approved
recipient.refusedRecipient refused
recipient.deletedRecipient removed

​
Withdrawal (withdrawal.*)

Events for wallet withdrawals. The data field contains the withdrawal object.
CodeDescription
withdrawal.requestedWithdrawal requested
withdrawal.paidWithdrawal paid
withdrawal.rejectedWithdrawal rejected

​
Invoice (invoice.*)

Events for the lifecycle of invoices generated by the billing engine. The data field contains the invoice object (prefix inv_).
CodeDescription
invoice.issuedInvoice issued
invoice.payment_attemptedInvoice charge attempt
invoice.paidInvoice paid
invoice.voidedInvoice voided
invoice.refundedInvoice refunded
invoice.rescheduledInvoice rescheduled
In the invoice.payment_attempted event, data carries the result of the charge attempt (and the referenced invoiceId), not the full invoice object.

​
Subscription (subscription.*)

Events for the lifecycle of billing engine subscriptions. The data field contains the subscription object (prefix sub_).
CodeDescription
subscription.createdSubscription created
subscription.activatedSubscription activated
subscription.canceledSubscription canceled
subscription.cycle_advancedNew subscription cycle started
subscription.pausedSubscription paused
subscription.resumedSubscription resumed

​
Fetch the catalog from the API

You can retrieve the same list (code + description) dynamically. The endpoint requires authentication via 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" }
  ]
}
Pass the desired codes in the events array. An empty array ([]) makes the webhook receive all events.
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"
  }'
Details on creating, updating, and validating signatures can be found in Webhooks · Overview.

​
See also

Webhooks · Overview

How to register webhooks, validate signatures, and reprocess deliveries.

Transactions

The transaction object sent in transaction.* events.

Payments

The payment object sent in payment.* events.

Subscriptions

Invoices and subscriptions that trigger invoice.* and subscription.* events.