Follow the steps in this guide to configure a new webhook using the Webhooks API resource. This generates a webhook ID to use in future requests and a secret to use in the validation procedure to secure your webhook. See Add a Webhook in API Reference for field definitions.

Prerequisites

1. See Create a Sandbox Account to sign up and log in to the Maast Manager portal.

2. Follow the steps in Get Your API Credentials to save a sandbox ID and API key.

3. See Authentication to format the credentials and generate your API token. (Alternatively, use the credentials as-is to test this endpoint with our 'Try It!' feature.)

4. Set up a webhook endpoint (notification_url) on your server to listen to POST requests. See Webhooks: Configure Your Server for more information.

Implement

1. Write a POST request to send to the /platform/webhook endpoint. In the request body, include the notification_url and a label to identify the webhook (label).

See the sample code below:

curl --request POST \
     --url https://api-test.maast.com/platform/webhook \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: application/json' \
     --data '
{
     "label": "Test",
     "notification_url": "https://<domain>/<>"
}
'

2. Optionally, add at least one type of event that will trigger the POST request.

   • Refer to the Webhook Events table in Webhook Conventions for available events.
   • Add the events in an events array in the request body.
   • You can add events later by sending an Add an Event request.

3. Optionally, include webhook settings fields. You may include the following:

   • webhook_node - The node at which the webhook will be created, such as a merchant ID. If this field is absent, the webhook is created at the API key's node.
   • email_address - One or more email addresses to notify when the webhook is suspended.
   • auth_type - The authentication type. If you set the type to BASIC, you should include an auth_settings object.
   • auth_settings - If auth_type is BASIC, add this object containing a user name (user_name) and/or password (user_password).

Once configured, your request will resemble the sample code below:

curl --request POST \
     --url https://api-test.maast.com/platform/webhook \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: application/json' \
     --data '
{
     "webhook_node": "210000000289",
     "label": "Test",
     "notification_url": "https://<domain>/<>",
     "email_address": [
          "[email protected]"
     ],
     "events": [
          "subscription_suspended"
     ],
     "auth_type": "BASIC",
     "auth_settings": {
          "user_name": "Test",
          "user_password": "password"
     }
}
'

Integrate

Send your request. You will receive a response like this from the Maast server:

{
  "code": 0,
  "data": {
    "webhook_id": 123,
    "notification_url": "https://<domain>/<>",
    "events": [
      "subscription_suspended"
    ],
    "webhook_node": 210000000289,
    "label": "Test",
    "status": "ACTIVE",
    "auth_type": "BASIC",
    "auth_settings": {
      "user_name": "Test",
      "user_password": "password"
    },
    "email_address": "[\"[email protected]\"]",
    "security_key": "88a74072064011eeb2720604d71ab08f"
  },
  "message": "Success"
}

Check the code field in the request response: 0 confirms that you have successfully created the webhook. If the value is something other than 0, check Platform API Response Codes in Reference.

The data object shows information about the webhook. See Add a Webhook in API Reference for field definitions.

Save the webhook_id value, found in data. You will need this to interact with this webhook later.

Save the security_key value, found in data. You will need this to validate the webhook. See Secure Your Webhook for more information.

🚧

Save Your Webhook ID

Save the webhook_id value that appears in your request response. You will need it to interact with this webhook using Webhook APIs.

🚧

Save Your Security Key

Be sure to save the security_key value that appears in the response. You will need it to validate the origin of the request sent to your webhook URL.

Test and Go Live

See our Test and Go Live guide to test your API integration and to start transacting with an active production account.

🚧

Validate in Production

When moving to production, you must redo the validation process for your webhooks configuration.