MX provides webhooks that send HTTPS POST callback requests to the URL of your choice. This enables you to subscribe to certain events, be notified when those events occur, and have information related to that event delivered to you. If you are subscribed to multiple events, a different URL can be configured for each event.

You can set up and configure webhooks on the client dashboard.

Index

Connection Status

Aggregation

Balance

History

Statement

Assets

Features

The current version of webhooks in the MX Platform API has the following features:

• Webhooks are delivered via RESTful HTTPS requests to the partner’s listening service;
• Webhooks are triggered when a qualifying event occurs in the MX system;
• Webhooks can make requests to any specified URL;
  • Configuration for this is done offline, out of band;
• Each POST request includes a JSON-formatted payload;
• The frequency of request retries diminishes over the course of approximately 24 hours, with no more than 12 total retries after an initial request.

Security

All webhook requests are encrypted by default. However, MX recommends using an additional layer of security as well. One or more of the following are typical:

1. HTTP basic: Provide MX with a username and password for making basic HTTP requests to your chosen URL;
2. Mutual certificate authentication: Both the partner and MX exchange certificates, which are then passed and verified at the time of a request; certificates may be from a commercial certificate authority or custom;
3. OAuth 2 bearer token (client credentials) authentication: Provide MX with an id and an access token; these are used to access a URL which provides a bearer token; this bearer token is then used to access the provided webhook URL until the bearer token expires after a pre-determined period of time; MX then repeats the process.

Retries and errors

MX webhooks will automatically retry a request in the case of a failed delivery such as a connection timeout, write timeout, read timeout, DNS error, etc.

The schedule of retries incorporates randomness so as to avoid a flood of requests to your system. Retries decrease in frequency with each attempt. You can expect to see a number of retries within the first hour of the initial attempt; gradually, retries will become less frequent.

If the webhook cannot be successfully delivered after 12 successive retries, it will not be delivered.

Example retry schedule