Callback Events
Security Note: Callbacks can only be managed using your Secret API Key, not your Public Key. This is for security purposes, as callbacks have access to sensitive event data.
When setting up a callback, you need to specify which events you want to subscribe to. Multiple events can be specified as a comma-separated list. Below is a comprehensive list of all events you can subscribe to.
Event Format
resource.action
naming convention. For example, payment.created
represents the event that occurs when a payment is created.Payment Events
payment.created
Triggered when a new payment is created but not yet processed.
payment.updated
Triggered when payment details are updated.
payment.completed
Triggered when a payment is successfully completed.
payment.failed
Triggered when a payment fails to process.
payment.refunded
Triggered when a payment is refunded, either partially or fully.
payment.disputed
Triggered when a payment is disputed by the customer.
Payout Events
payout.created
Triggered when a new payout is created.
payout.updated
Triggered when payout details are updated.
payout.completed
Triggered when a payout is successfully completed.
payout.failed
Triggered when a payout fails to process.
payout.canceled
Triggered when a payout is canceled.
Customer Events
customer.created
Triggered when a new customer is created.
customer.updated
Triggered when customer details are updated.
customer.deleted
Triggered when a customer is deleted.
Payment Link Events
payment_link.created
Triggered when a new payment link is created.
payment_link.updated
Triggered when a payment link is updated.
payment_link.deleted
Triggered when a payment link is deleted.
payment_link.visited
Triggered when a payment link is visited by a customer.
Subscription Events
subscription.created
Triggered when a new subscription is created.
subscription.updated
Triggered when a subscription is updated.
subscription.canceled
Triggered when a subscription is canceled.
subscription.renewed
Triggered when a subscription is renewed for a new billing period.
subscription.payment_failed
Triggered when a payment for a subscription fails.
subscription.payment_succeeded
Triggered when a payment for a subscription succeeds.
Webhook Delivery
When an event occurs, our system will send a POST request to the URL you specified when creating the callback. The request will include an Event object in the body with the following structure:
{ "id": "zp_event_1234567890", "type": "payment.completed", "created": "2023-01-15T14:30:45Z", "data": { "object": { // The object related to this event (e.g., payment, payout, customer) "id": "payment_abc123", // ... other object properties } } }
Handling Webhook Failures
If our system fails to deliver a webhook (e.g., if your server responds with a non-2XX status code), we'll automatically retry several times with an exponential backoff strategy. After multiple consecutive failures, the callback will be marked as failing and you'll need to update it or fix your endpoint.