Integrate your IBM webMethods Integration workflows with external web services with webhooks. Learn how to configure webhooks in IBM webMethods Integration, how incoming webhooks work, and how to post data to IBM webMethods Integration using webhooks.
Webhook is one of the many ways to integrate IBM webMethods Integration with various external apps or services. Let’s go step by step to understand what webhooks are and how they work.
A webhook is a user-defined HTTP callback. IBM webMethods Integration supports incoming webhooks.
Incoming webhooks allow external sources to notify IBM webMethods Integration about a specific event.
If webhook is switched ON for a workflow, IBM webMethods Integration creates a unique webhook URL, for example, https://demo.int-aws-us.webmethods.io/runflow/run/24EjeBp5R2 for that workflow. You need to submit this URL to an external source. This external source can be any web service or app that is capable of making HTTP POST requests. As soon as an event occurs in this external source, it will send a JSON payload via an HTTP POST request to IBM webMethods Integration. This payload contains the details of the event.
A webhook can work as a trigger for your workflow. To do this, create a workflow as per your requirements. Instead of setting a trigger, enable Webhook and provide the webhook URL to an external source.
For instance, you can provide the webhook URL to Evernote, and define that the URL should be notified whenever a new note is created in your account. Now, whenever a new note is created in your Evernote account, Evernote will make an HTTP POST request (with details of the created note in its body). This will trigger off the workflow immediately.
So, to summarize, if you create a workflow with webhook switched on, the workflow will run automatically whenever an HTTP POST (with payload) or HTTP GET request is made to the webhook URL.
To enable webhooks, hover over the Start button and click on the Settings icon or double-click on the Start button. From the list of trigger services that appear, click on Webhook and then click Next. You will see the webhook configuration window as shown below:
This option lets you add payload for Webhook. The structure of the payload you add here should be similar to the one that the webhook is expected to receive in future. IBM webMethods Integration uses this data to display the output of the webhook in the subsequent actions of your workflow.
To configure webhook payload , click the Next button.
There are two options through which you can add webhook payload:
You can use this method to send realtime webhook payload through Postman or browser. This allows you the flexibility to send custom realtime webhook data at the time of sending the request to webhook through any app capable of making REST API requests (like Postman) or any browser.
To do this, follow the instructions given below:
Copy the randomly generated Webhook URL.
Paste this Webhook URL in any webhook provider that is capable of sending POST requests. Here in our example, we will be using Postman. Enter the details in Headers and Body as per your requirement and then click on the Send button. Once you do that, you will see the following window:
Next, navigate back to the Webhook configuration window in IBM webMethods Integration and click on Fetch to retrieve the Webhook payload data. On clicking the button, the Headers, Body, and Query fields will get autofilled with the data you sent through Postman.
Once you are done with this, click Next.
Using this method, you can manually add webhook payload data. However, you will have to ensure that the structure of the payload you add is similar to the one that the webhook is expected to receive in the future. IBM webMethods Integration uses this data to display the output of the webhook in the subsequent actions of your workflow.
To do this, in the Webhook page, enter the payload data in the text fields, Headers, Body, and Query, in JSON format.
Once you are done with this, click on Next.
You can add an extra layer of security to your webhook data by either marking the webhook as private or by setting an authentication method for it.
All webhooks are public by default. You can mark an individual webhook as private by enabling the Private Webhook option.
When a webhook is marked as private, it cannot be accessed over a public network. It can only be accessed using API Gateway.
When the Private Webhook is enabled, the Webhook URL shows two distinct URLs:
Internal url: An internal endpoint is accessible only from webMethods network. You can view and copy the URL details using the copy icon alongside.
Private url: A private endpoint is used when a private network is configured. Access is limited exclusively to your private network, preventing any outside access, including from your network or webMethods applications within your tenant. You can view and copy the URL details using the copy icon alongside.
You can optionally set an authentication method for your webhooks to enhance their security.
Select this option if you do not want to apply any authentication mechanism on your webhook data.
You can secure the webhook by selecting the Tenant Credentials option. This will require the users of this webhook to provide the tenant credentials first before they can send an execution request.
The webhook key functionality allows you to generate a secret webhook key, which you need to send in the headers as webhook_key while sending the webhook execution request.
To do this, click GENERATE TOKEN to generate a random token for webhook key (for example, 6f9a1854848sample663157d1460712634541)
You can optionally enable the Return Data on Sync Webhook action to automatically attach it as the last action of your workflow by enabling the toggle button. This action will fetch the workflow output and send it back to the webhook. Read more about how Return Data on Sync Webhook works.
Read more about how Return Data on Sync Webhook works.
Once you have configured the required settings, click Next.
Once you have configured all the webhook settings, you will see a screen with the webhook URL which you can submit to external applications and the mock payload data provided by you, which will be used to configure the rest of the workflow.
Click on Done to return to canvas.
With this, you have successfully configured a webhook for your workflow.
Let’s now see how to make a POST request using webhook URL and how to use the configured webhook payload in the subsequent actions.
To do so, we will add Trello - Add Card action to workflow.
Use the name key from webhook payload as input in the Card Name field and configure the rest of the action as you would normally do.
Next, pass the details of the created card back to Postman using Return Data on Sync Webhook action.
After this, click Next, Test the action, and click Done.
You will be redirected to the canvas.
Now, copy the webhook URL from the webhook trigger window, and paste it in the Request URL field in the Postman app. Add relevant webhook payload data and click Send.
This will execute the workflow associated with the specified webhook URL, where the configured runtime payload will be used to create a new Trello card and you will see the details of the Trello card in the Postman response.
You can also regenerate the webhook URL for an existing workflow. This ensures that your workflow will remain secure even if the webhook URL is compromised. To do this, follow the instructions given below:
Open an existing workflow of which webhook URL you wish to reset and double-click the Start icon (which now shows the webhook icon). A webhook configuration window appears. To do this, follow the steps given below:
Click on the Reset webhook button given beside the Delete button. You will see that the URL given under the Webhook URL field has been changed.
Click Done. You will be redirected to the canvas.
Save the workflow. This will enable the regenerated webhook URL for your workflow.
Now when you run this workflow using an older webhook URL link, you will receive an error.
Let us understand how to pass large data and use it in an action with the help of an example.
Add Send an Email action to the IBM webMethods Integration canvas, and connect it to Start and Stop to create a workflow.
Configure the Send an Email action, and fill up all the fields. In the Body field, enter {{request}}. This ensures that the data you pass in the webhook URL will be fetched in the body of the email. You can also fetch individual elements of the data by using the key name with $request.body. For example, {{$request.body.title}} or {{$request.body.id}}.
Once you have entered these details, click Next, test the workflow, click Done, and then Save this workflow.
In Postman, select the HTTP request as POST and enter the Webhook URL in the given field.
In the Authorization field, select the Type of account you want to provide. If you have selected the User Auth method while activating the webhook, select Basic Auth type from the drop-down list and if you have selected the Auth token method while activating the webhook, you need not select an authorization type.
Under Headers, put Content-Type as application/json.
In the Body field, select raw and enter the data that you want to pass in JSON format.
Once you are done, click Send located on the top-right corner of the page. As soon as you click Send, the workflow will run automatically. As a result, the recipient (specified in the Send an Email action) will receive the data passed in the email body (in JSON format).
You can set parameters (key value pairs) through the Webhook URL directly.
Let’s say your Webhook URL is https://demo.int-aws-us.webmethods.io/runflow/run/24EjeBp5R2 and you are trying to pass the value apple under the parameter fruit. You can do so by running the following Webhook: https://demo.int-aws-us.webmethods.io/runflow/run/24EjeBp5R2?fruit=apple.
Now if you want to use this value in any operation, use {{$request.body.fruit}} in the given field.
You can manage all webhooks associated with your project workflows through the Events tab of your project. To do so, follow the instructions given below:
Go to the project that contains the workflow of the webhook settings you want to update.
Click Events. All event groups supported in IBM webMethods Integration appear.
Click Webhooks. The list of all webhooks appear. Additionally, you can find the names of all the workflows utilizing the webhook, as well as information on whether the webhook is marked as private or public, along with their respective webhook URLs. You can also click the URL icon to copy the webhook URL.
[Optional] Click the vertical ellipsis icon corresponding to the respective webhook to do the following:
Refresh Webhook URL: Webhook URL gets updated automatically.
Webhook Authentication: Update the authentication details of the Webhook. For more information about adding or modifying authentication for a webhook, see Webhook Authentication.
View Webhook Payload: Displays the webhook payload. To modify it, go to the workflow and modify the payload through the canvas.