Triggering an MPO Task via Mambu Webhook

Jump to Section

In most cases, Mambu Process Orchestrator (MPO) tasks are triggered by external events, with MPO acting as a middle layer that responds by executing business logic. In this documentation, we will use the Mambu Banking Engine as the external service triggering a task, but any external service that can send webhook notifications is capable of triggering MPO tasks.

Getting the webhook URL for an MPO process

To trigger an MPO task, begin by getting the webhook URL to start a new task. To do this, select the Start node of the process that you want to trigger. In the info panel on the right-hand side, enable Direct url for tasks upload, and select Copy webhook via JSON. Save the copied link as we will use it later.

Getting the Direct Webhook URL in MPO

To find the webhook URL for an Alias, see Finding out more about an alias.

Please Note:
The webhook URL used to initiate a task is secured by the SHA-hashed signature at the end of the URL.

Preparing Mambu to trigger an MPO task

Before you start, define the conditions to trigger the webhook and the JSON payload to send to MPO when the event is triggered.

To create a webhook in the Mambu UI do the following:

Log in to your Mambu instance at https://TENANT_NAME.mambu.com or use your sandbox instance at https://TENANT_NAME.sandbox.mambu.com.
On the main menu, go to Administration > Webhooks.
If Webhook Communications is set to None, change it to Enabled and select Save Changes. Otherwise continue to Step 4.
Open the Notifications tab and select Add Notification.
Enter a name for your webhook.
Select Opt-out underneath Option. This ensures the webhook automatically applies for all of your clients and accounts. Opt-in requires you to enable this webhook notification for each account you have in your instance.
In the Conditions section you can define the conditions that trigger the webhook. For more on the conditions you can set, see Fields for a webhook.
Enter the URL that you saved from the Getting the webhook URL for an MPO process section in the Web Hook URL input.
Set the Request Type to POST, set Authorization to No Authorization and set Content-Type to application/json.

Configuration settings for creating a Mambu webhook that starts a task in MPO

In the text box, enter a JSON-formatted payload to send with the webhook. You can search under Placeholder for pre-defined patterns to use to pull in any field from Mambu.

Adding a placeholder top the webhook notification

You can preview the JSON payload by selecting the Preview button. When you are done select Save Changes.

Please Note:
No validation is done on the JSON payload you create. An incorrectly formatted payload will cause errors in MPO when it is sent from Mambu.

For more on how to create webhooks in Mambu, see Defining a New Webhook.

Security Enhancement

You can optionally enhance security at the Start node of a Process by enabling basic authentication, ensuring username and password protection for receiving requests via Direct URL in user companies:

In the node settings, select Basic in the Type auth dropdown list.
Enter the username and password, and select the checkbox to save your authentication.

All the requests that don’t contain authorization header will not be processed, and the Access denied error will be returned.

Switching off the Basic Authentication:
If you switch back to No Auth in the Start node settings, you will turn off the authentication and reset the credentials for this node. Thus, turning the authentication on again will require re-entering credentials.

Using aliases with the Basic Authentication:
If you have an alias linked to a process in which you’ve activated the basic authentication, sending data to the alias' Direct URL also requires sending authentication credentials. Sending requests to the alias' Direct URL with no credentials will result in the Access denied error.

Authentication credentials exposure:
Username and password credentials are fully displayed in the Start node settings in the Edit mode and on the Webhook tab of the View details menu for a Process.

Setting Authentication Variables for the Direct Webhook URL in MPO To conceal basic authentication credentials, use variables with credentials. For example, you can use the webhook-var variable with the following constructions:

{{env_var[@webhook-var].user}} for the username field
{{env_var[@webhook-var].pass}} for the user password field, where webhook-var is the name of the variable with your credentials.

Using Authentication Variables for the Direct Webhook URL in MPO

Tutorials