Defining a New Webhook

This page describes how to create webhook templates. For general information on webhooks, see Webhooks Overview.

To create webhooks you must either have the Create Templates (CREATE_COMMUNICATION_TEMPLATES) or Edit Templates (EDIT_COMMUNICATION_TEMPLATES) permissions.

Create a webhook

To create a new webhook:

1. On the main menu, go to Administration > Webhooks > Notifications.
2. Select Add Notification.
3. Enter all the necessary information in the Creating A New Webhook Notification dialog. See below for more information on the fields.
4. Select Save Changes.

Once you create a webhook, it is added to the list of webhooks indicating the state and status of each webhook.

If a webhook state is In Use it means that at least one webhook notification has been sent using that webhook template, whereas if it's Not In Use the webhook template hasn't been used for any webhook notifications yet.

If a webhook template status is Active it's available and can be used, whereas if it's Inactive it means that it is currently deactivated and that it can't be used to send notifications.

Fields for a webhook

Below is a description of the available fields when creating a webhook.

Webhook name

The human readable name identifying this webhook. It must be unique and must be a maximum of 255 characters.

Subscription option

Defines whether individual clients or groups are automatically subscribed to trigger a webhook when a certain event occurs.

If you select Opt-Out, then individual clients and groups are automatically subscribed to trigger webhooks. This is the most common option so that you are informed of actions that happen for all your individual clients and groups.

If you select Opt-In, then you must manually subscribe individual clients and groups to trigger webhooks. For more information, see Subscribing or unsubscribing a client from a webhook.

Target

Defines what entity is being monitored to trigger this webhook. This will have an effect on what events are available for triggering this webhook. The entities available are individual clients, groups, end of day processing, and data access.

If you have the Payments capability enabled, then you will also have the payment order target available. For more information, see Payment events.

Event trigger

The list of events available for use as a trigger will depend on the Target selected for this webhook. For more information on each event, see Event Triggers for Notifications.

Conditions

You may create additional conditions that need to be met in order for a webhook notification to be sent.

Most conditions are made up of a field or piece of information that is monitored, an operator, and a value.

To set up a condition:

1. Select the field or piece of information to monitor. The available options will depend on the target, recipient, and event trigger selected.
2. Select the operator. The available options will depend on the option you selected in step 1.
3. If appropriate, enter the value(s).

To remove conditions, select the Delete icon .

To create more conditions, select Add Condition.

In the dropdown, selecting Match All sends a notification if all of the conditions are met. Selecting Match Any sends a notification if at least one of the conditions is met.

For example, you may want to create a webhook when a deposit is made but only when the deposit amount is greater than USD1,000.

Webhook URL

The endpoint to which this webhook should be sent. It is possible to use placeholders in the URL. Including as the value of query parameters. For more information, see Placeholders.

The webhook system will encode any non-ACSII characters and spaces which may occur in the values of replaced placeholders to make your request URL safe. If you are supplying any additional static values for query parameters, please ensure they are also properly URL safe or percent encoded when setting your webhook URL or sending may fail.

Request type

The REST method to be used for this call. The available methods are POST, PUT, and PATCH.

Authorization

The type of authorization used, the options are No Authorization or Basic Authorization. If you select basic authorization, then you will have to enter a username and password for the endpoint to receive calls. If you are using API token based authorization, you can select 'No Authorization' and provide your API token as a custom request header.

Content type

This defines how data will be sent to your endpoint and will be included as header in API requests. This should match with the accepted media type of your target endpoint. The available options are plain text, application/json, or application/xml.

Custom request headers

You may set up any additional custom request headers. Selecting Add Header will reveal two fields. The first field is for the header name, and the second field is for the value. To remove a header select the Delete icon .

Webhook contents

The content to be used as the payload for your request here. For JSON or XML content types you are advised to validate your payload using an external service such as JSON Lint before saving as there is no validation done on this field by the Mambu system.

You may use placeholders in your webhook contents. Placeholders allow you to include relevant information for each individual webhook notification. For more information, see Placeholders.

Subscribing or unsubscribing a client from a webhook

The subscription option of a webhook determines whether a client is automatically subscribed to trigger a webhook. For more information, see Subscription option.

To edit which webooks a client is subscribed to trigger:

1. Go to the profile of the client.
2. In the top right-hand corner select More > Set Notifications.
3. In the Notification Requests dialog, select the webooks that you would like the client to be subscribed to.
4. Select Save Changes.

The notifications in the Notification Requests dialog are listed by the name of the event trigger and in parentheses they list whether they are SMS, email, or webhook notifications.

Control over which notifications a client or group is subscribed to trigger is managed at the level of the event trigger. For example, if you three different webhooks set up for the Client Activity event trigger, only one Client Activity (Web Hook) checkbox will appear in the Notification Requests dialog. You have to select whether you want to subscribe a client or group to trigger all of them or none of them.

Testing your webhook configuration

We recommend using services such as RequestBin  or Webhook Tester to test your webhook callbacks if you can not access server logs for live debugging, which can sometimes be the case if you are sending data to a third party system. These services allow you to define temporary dummy endpoints which will show you the requests and all the data you are receiving from Mambu.

Sender IP Addresses

Webhook requests to your endpoints will originate from a fixed set of IP addresses per Mambu region. These IP addressed can be whitelisted in your firewall. Any changes to IP addresses will be announced on our Status Page as well.

If you need to know the sender IP addresses for your environment, please contact us through Mambu Support.