Integrate your webMethods.io Integration workflows with external web services with webhooks. Learn how webhooks works, how to configure webhooks in webMethods.io Integration, how incoming webhooks work, and how to post data to webMethods.io Integration using webhooks.
Webhook is one of the many ways to integrate webMethods.io 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. webMethods.io Integration supports incoming webhooks.
Incoming webhooks allow external sources to notify webMethods.io Integration about a specific event.
If webhook is switched ON for a workflow, webMethods.io 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 webMethods.io 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. You will see the webhook configuration window as shown below:
The webhook URL for that particular workflow is given on the top of the window. You can copy this webhook URL using the Copy icon given beside the webhook URL. You can also reset it to obtain a new webhook URL, or delete it using the refresh and delete icons respectively.
You can secure your webhook data by using either Auth Tokens or Tenant Credentials. To do so, switch-on the Webhook Authentication toggle button. You will see two options:
The Auth token functionality allows you to generate a secret token, which typically becomes part of your webhook URL, and acts as a unique identifier when submitting to any external web service.
To do this, click GENERATE TOKEN to generate a random auth token (e.g., 6f9a1854848sample663157d1460712634541)
Next, append this randomly generated auth token to your webhook URL. The format in which you will do that is: ‘webhookURL ?authtoken= authtoken’. So, your webhook URL, which was earlier https://demo.int-aws-us.webmethods.io/runflow/run/24EjeBp5R2, now becomes, https://demo.int-aws-us.webmethods.io/runflow/run/24EjeBp5R2?authtoken=6f9a1854848sample663157d1460712634541. You can now use your new, secured webhook URL or submit this URL to any web external service for triggering a workflow. Since the new token is only known to you, it enhances the security of your webhook.
Note: You can also change the token at any time by clicking on the GENERATE TOKEN button. If you change the token of your webhook, ensure to make relevant changes in the corresponding webhook URL too.
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.
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. webMethods.io Integration uses this data to display the output of the webhook in the subsequent actions of your workflow.
Note: For both AWS and Azure, webhook payload is supported up to 5 MB.
To configure webhook payload , click on the Next button.
You will see 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:
Note: While configuring the request, ensure that you provide the request body in JSON format and set the content-type to JSON (Application/JSON).
Next, navigate back to the Webhook configuration window in webMethods.io 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. You can optionally enable the Return Data on Sync Webhook action to fetch workflow output and send it back to webhook using the toggle button. (Read more about how Return Data on Sync Webhook works)
Once you have added the payload, click on Next. You will see the webhook payload data provided by you, which will be used to configure the rest of the workflow. Click on Done to return to canvas.
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. webMethods.io Integration uses this data to display the output of the webhook in the subsequent actions of your workflow.
To do this, in the Webhook window, 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 optionally enable the Return Data on Sync Webhook action to fetch workflow output and send it back to webhook using the toggle button.
Note: If you enable Return Data on Sync Webhook for your webhook, and it doesn’t get any response for 60 seconds after the triggering event, the workflow will get timed out. (Read more about how Return Data on Sync Webhook works)
Once you have added required payload data, click Next.
You will see the webhook payload data provided by you, which will be used to configure the rest of the workflow. Click on Done to return to canvas.
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 Next. 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 webMethods.io 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}}.
Note: webMethods.io Integration automatically converts all the header-keys to lowercase while sending the data to the webhook. So if you wish to retrieve the value of a specific header-key, ensure that you enter the key name in lowercase. For example, if the actual header key is Name, enter {{$request.header.name}} to retrieve its value in the workflow, otherwise, it will return an empty response.
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 Configuration tab of your project. To do so, follow the instructions given below:
Navigate to the project that contains the workflow of the webhook settings you want to update.
Click on the Configuration tab. You will be redirected to the Certificates screen by default.
Click on the Workflow tab and then click Webhooks to view and manage your project webhooks. Here, you can see the name of each workflow in which the webhook is being used, along with its corresponding webhook URL. You can copy the Webhook by clicking on the copy icon given beside the webhook URL.
If you want to refresh the Webhook URL, view the payload being used for a particular webhook or add authentication to it, click on the vertical ellipsis icon given against the respective webhook.
Select the required option from the list of options that appear.
Refresh Webhook URL: Once you click on this option, the Webhook URL gets updated automatically.
Webhook Authentication: When you click on this option, you will be redirected to the Webhook Authentication window. You can see the Webhook Authentication section in this document for information.
View Webhook Payload: Click this option to view the webhook payload. To modify it, navigate to the workflow and modify it through the canvas.