Defining a New Webhook
- 15 Nov 2021
- 4 Minutes To Read
-
Print
-
DarkLight
-
PDF
Defining a New Webhook
- Updated On 15 Nov 2021
- 4 Minutes To Read
-
Print
-
DarkLight
-
PDF
Create a webhook
To create a new webhook:
- On the main menu, go to Administration > Webhooks > Notifications.
- Select Add Notification.
- Enter all the necessary information in the Creating A New Webhook Notification dialog. See below for more information on the fields.
- Select Save Changes.
Fields for a webhook
| Name | Options | Description |
|---|---|---|
| Name | free text | The human readable name identifying this webhook. A webhook is uniquely identified through its name, hence for every new definition, a distinct and easily identifiable name should be used. |
| Option | - Opt-in - Opt-out |
Defines whether individual Clients and Groups need to be manually subscribed (opt-in) to trigger this webhook or are subscribed by default (opt-out). This option is not available for webhooks targeted on Data Access and End of Day Processing |
| Target | - Clients - Data Access - End of Day Processing - Groups |
Defines what entity is being monitored to trigger this webhook. This will have an effect on what events are available for triggering this webhook. Check out our webhooks Showcase section for example use-cases. |
| On Event | any Target-related event | The list of events available for use as a trigger will depend on the Target selected for this webhook |
| When | any Event-related property | Conditions for the trigger, for example, Deposit Amount > 1,000. Any number of conditions can be added and you can chose to trigger the webhook when all conditions are met, or any one of them. Nesting conditions is not possible. |
| Web Hook URL | a valid URL | The endpoint to which this webhook should be sent. The URL field will not be validated on save, so it is a good idea to copy and paste your endpoint URL into this field. It is also strongly recommended that the endpoint is authenticated, is secure, and has a valid SSL certificate. It is possible to use placeholders in the URL, please see below for more information. |
| Request Type | - POST- PUT- PATCH |
The REST method to be used for this call. If you are unsure of which to select consult the API documentation of the service to which you are sending this webhook or consult with your IT department if this is an internal service. |
| Authorization | - No Authorization - Basic Authorization |
Whether the endpoint is open or requires a username and password to receive calls. If using API token based authorization, you can leave this setting as 'No Authorization' and provide your API token as a custom request header. |
| Content Type | - Plain Text - application/json - application/xml |
This defines how data will be sent to your endpoint and will be included as header in requests. This should match with the accepted media type of your target endpoint. |
| Custom Request Headers | - A valid header | Selecting Add Header will reveal two fields. The first field is for the the header name, and the second field is for the value. To remove a header select Delete . Please note: you can not use placeholders to dynamically set header values, these fields are only intended for static data that will not need to be changed from one webhook to the next, such as an API authentication token or a custom value for the user-agent header to better identify Mambu webhooks in your callback receiver . |
| Content | free text/json/xml | Enter any 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. |
| Placeholder | Target-related placeholders | Placeholders can be used in both the Web Hook URL and Content fields. Selecting from the drop-down list will give you the related placeholder for that data point which you can copy and paste into the desired field. |
You will probably want to use an Opt-Out scheme for your webhooks since all existing targets (clients), as well as all newly created ones will be automatically associated with this trigger. However, opting clients in manually is also possible using the same steps as for email and SMS notifications.
Enter the URL of your endpoint where your application "resides." Mambu will call your application with an HTTP POST/PUT/PATCH request when this trigger event occurs.
You can enter any data you like using placeholders, specify the format and structure it according to the needs of your application.
Validation
Remember to validate your payload before testing and saving your webhook as errors can occur if JSON or XML schemas are not used correctly. For example, not enclosing strings in
" quotation marks in JSON may cause these to be ignored by the receiving application or the data to not to be sent at all.
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 3rd 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 on your firewall. Any changes to the set of IP addresses given below will be announced on our Status Page as well.
If you are on a private Mambu deployment and need to know the sender IP addresses for your dedicated environment, please contact us through Mambu Support.
| Region | Production | Sandbox |
|---|---|---|
| US Region (N. Virginia) | 52.200.155.15852.203.173.35 |
52.201.89.67 |
| EU Region (Ireland) | 52.50.237.24152.51.211.17 |
52.51.53.69 |
| EU Region (Ireland) 2 | 52.50.189.7534.248.61.22463.35.141.142 |
52.31.193.183 |
| Asia Pacific Region (Singapore) | 52.221.166.2052.76.153.243 |
52.74.50.70 |
| Asia Pacific Region (Sydney) | 52.62.39.18352.63.160.42 |
52.63.147.3352.63.128.125 |
If you have a question about how anything works or have come across something you haven't seen explained here, get in touch with our community of fellow users and Mambuvians where someone will lend a hand.
Was This Article Helpful?
