Webhook Subscription

Webhooks are the best way for your application to get real-time notifications about events happening in our system, like a failed transaction or a settled batch. Instead of you constantly polling our API to check for updates (pull), our system will automatically send a notification (push) to your application the moment an event occurs. This is more efficient and reliable.

This guide covers how to set up, secure, and manage webhook subscriptions.

How Webhooks work?

The process is simple:

1. You Subscribe: You tell us which events you're interested in and provide a secure HTTPS URL (an "endpoint") that you control.
2. An Event Occurs: When one of those events happens on a merchant's account (e.g., a transaction fails), our server generates a JSON payload with details about that event.
3. We Send a Notification: We immediately send that JSON payload as an HTTP POST request to your registered URL.
4. You Acknowledge Receipt: Your server should respond with a 200 OK status code to let us know you received the notification successfully.

Note: Webhooks are not guaranteed to be sent in any specific order. Always check the event timestamp in the payload to understand the sequence of events.

Setting up a Webhook Subscription

Follow these steps to create and manage your webhook subscriptions.

Step 1: Discover Available Events

• Before you can subscribe, you need to know what events are available. Check out Webhook event types page to view the full list of subscribable event types
• This will return an array of event types you can use in the next step.

Step 2: Create the Subscription

• To create a new event subscription, make a POST request to the endpoint PUT checkout/v3/subscription.
• This call registers your URL to receive notifications for a specific eventType

Step 3: Confirm the Subscription was Created

• While not required, you can confirm your subscription details immediately by adding the echo=true query parameter to your creation request. This will return the full subscription object in the response, which is useful for debugging.
• You can also view the list of subscribed notifications by making a request GET checkout/v3/subscription

Request Body Parameters

When creating a subscription, your JSON request body should include the following parameters:

Available Sources

The Sources parameter allows you to filter notifications based on where the transaction originated.

• API: Transactions created via direct API calls.
• Invoice: Payments made against an invoice.
• Link2Pay: Payments from a secure payment link. For notifications from Link2Pay sources, add a dash and the name of the payment link after Link2Pay in the sources field, i.e. Link2Pay - Example Payment Link.
• MXExpress: Transactions from the MX Express mobile app.
• MXRetail: Transactions from a retail terminal.
• Order: Payments associated with an order.
• QuickPay: Payments processed through the QuickPay virtual terminal.
• Recurring: Automatically scheduled recurring payments.

Managing Subscription

To update an existing webhook subscription, use its unique id (retrieved from the GET /checkout/v3/subscription response). Pass the eventType and any updated fields in your request payload to the endpointPUT checkout/v3/subscription

Best Practices (Security & Reliability)

Following these practices is essential for a robust and secure webhook integration.

1. Ensure Idempotency

Our system may send the same webhook more than once due to network issues. Design your system to be idempotent by tracking the unique eventId in each payload. This ensures that you can safely process the same event multiple times without creating duplicate records.

2. Secure your endpoint

⚠️

Important: Currently, webhooks do not include a cryptographic signature (e.g., HMAC or X-Webhook-Signature). Please implement the following best practices to secure your endpoint.

• Use a dedicated and private URL for receiving webhooks.
• Validate the merchantId in the payload to confirm it's a relevant event.
• Whitelist our server IP addresses, if they are provided.

3. Handle Acknowledgements & Retries

Acknowledgement Criteria:

• Your webhook endpoint must return an **HTTP 2xx response code **(e.g., 200 OK).
• This response must be received within 5 seconds.
• A simple body like "status": "received" is acceptable and useful for logging and will be recorded in our logs.

Retry Policy

• Webhooks are retried automatically if the initial attempt fails (non-2xx status, timeout, or network error), as long as the subscription and merchant are active.