Xenith uses webhooks to automatically notify your application about important events related to your transactions. These events include Pay In, Pay Out and Account Inquiry status changes, maintenance updates and Payment Link completion. See Webhook Events below.
When these events occur, Xenith sends a POST request to the callbackURL in your transaction request and to each Endpoint subscribed to the event in Webhooks & Events, with details about the event. This allows your application to receive real-time updates and take appropriate actions without needing to constantly poll our API.
Common Webhook Structure
All webhooks share a common structure:
| Field | Type | Description |
|---|---|---|
schemaVersion | string | Version of the webhook schema |
timestamp | string | Timestamp of the webhook event (UTC, ISO 8601 format) |
data | object | Contains transaction-specific details |
Webhook Events
| Event | Group | Sent when |
|---|---|---|
pay-in.successful | Pay In | A Pay In becomes SUCCESS. |
pay-in.failed | Pay In | A Pay In becomes FAILED. |
pay-in.expired | Pay In | A Pay In becomes EXPIRED. |
pay-in.refunded | Pay In | A Pay In becomes REFUNDED. |
pay-out.successful | Pay Out | A Pay Out becomes SUCCESS. |
pay-out.failed | Pay Out | A Pay Out becomes FAILED. |
pay-out.cancelled | Pay Out | A Pay Out expires. |
pay-out.refunded | Pay Out | A Pay Out becomes REFUNDED. |
account.inquiry.completed | Account Inquiry | An account inquiry is completed. |
maintenance.started.payins | Maintenance | A Pay In maintenance starts. |
maintenance.started.payouts | Maintenance | A Pay Out maintenance starts. |
maintenance.completed.payins | Maintenance | A Pay In maintenance ends. |
maintenance.completed.payouts | Maintenance | A Pay Out maintenance ends. |
payment.link.completed | Payment Link | A Payment Link is completed. |
Pay In, Pay Out and Account Inquiry events go to the transaction's callbackURL and to every Endpoint subscribed to them. Maintenance and Payment Link events go only to Endpoints subscribed to them.
Webhook Response
Your system should immediately respond with a 200 status code upon receiving a webhook. If a failure occurs, automatic retry will kick-off for the next 24 hours. Refer to the Delivery Attempts and Retries section for more details.
Delivery is at least once, so the same Event can reach you more than once, for example after a retry or a resend. Use the Event ID to recognise repeats. Each destination is delivered and retried on its own. Events can arrive out of order; once a transaction has a newer status, Xenith stops sending its older Events.

