Webhooks

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:

FieldTypeDescription
schemaVersionstringVersion of the webhook schema
timestampstringTimestamp of the webhook event (UTC, ISO 8601 format)
dataobjectContains transaction-specific details

Webhook Events

EventGroupSent when
pay-in.successfulPay InA Pay In becomes SUCCESS.
pay-in.failedPay InA Pay In becomes FAILED.
pay-in.expiredPay InA Pay In becomes EXPIRED.
pay-in.refundedPay InA Pay In becomes REFUNDED.
pay-out.successfulPay OutA Pay Out becomes SUCCESS.
pay-out.failedPay OutA Pay Out becomes FAILED.
pay-out.cancelledPay OutA Pay Out expires.
pay-out.refundedPay OutA Pay Out becomes REFUNDED.
account.inquiry.completedAccount InquiryAn account inquiry is completed.
maintenance.started.payinsMaintenanceA Pay In maintenance starts.
maintenance.started.payoutsMaintenanceA Pay Out maintenance starts.
maintenance.completed.payinsMaintenanceA Pay In maintenance ends.
maintenance.completed.payoutsMaintenanceA Pay Out maintenance ends.
payment.link.completedPayment LinkA 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.