Integrate your webMethods.io Integration workflows with external web services with webhooks. Learn 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 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. 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 10 MB.
- The webhook payload data added in the source workflow is not retained when the workflow is cloned, imported, or deployed. You will need to reconfigure the webhook settings in each cloned, imported, and deployed workflow.
To configure webhook payload , click on 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:
Note: Currently, only JSON is supported. While configuring the request, ensure to 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.
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 add an extra layer of security to your webhook data by using either Tenant Credentials or Webhook Key. Here, you will see three options:
Note: All cloned, imported, and deployed workflows containing a webhook will by default have the webhook authentication method as ‘Tenant Credentials’ irrespective of the webhook authentication method configured in the source workflow.
Select this option if you don’t 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 (e.g., 6f9a1854848sample663157d1460712634541)
Notes:
- If you enable ‘Webhook Key’ authentication for your webhook, you will need to pass the webhook key in headers as “webhook_key” each time you send the webhook execution request.
- You can change the token at any time by clicking on the GENERATE TOKEN button. If you change the token of your webhook, ensure to send the updated token as the value of the “webhook_key” in headers while sending the webhook execution request.
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 workflow output and send it back to the webhook. Read more about how Return Data on Sync Webhook works.
Notes:
- When you enable ‘Return Data on Sync Webhook’ for your webhook, it expects a response within 180 seconds after the triggering event. If the response is not received within the specified period, the ‘408 Request Timeout’ error will be thrown. This error means the server chooses to terminate the connection rather than continue waiting for the response.
- However, if you are using any other web browsers, like Google Chrome, Microsoft Edge, etc., other than Mozilla Firefox, you may observe automatic retries performed by the browser before getting the ‘408 Request Timeout’ error. This means, your browser is automatically making multiple requests to get a response, and hence, you may have to wait for more than 180 seconds before you see the ‘408 Request Timeout’ error.
- If you are using services like Postman, and the response is not received within 180 seconds, the ‘408 Request Timeout’ error will appear soon after the timeout duration.
Read more about how Return Data on Sync Webhook works.
Once you have configured 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 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.
