Webhook

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.

What is a webhook?

A webhook is a user-defined HTTP callback. webMethods.io Integration supports incoming webhooks.

What’s an incoming webhook?

Incoming webhooks allow external sources to notify webMethods.io Integration about a specific event.

How does an incoming webhook work? How does it notify webMethods.io Integration?

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.

Incoming webhook as a trigger

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:

Webhook payload

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:

  1. Fetch Webhook payload automatically
  2. Add Webhook payload manually

Method 1: Fetch Webhook payload automatically

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:

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).

Method 2: Add Webhook payload data manually

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.

Webhook authentication

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.

None

Select this option if you don’t want to apply any authentication mechanism on your webhook data.

Tenant Credentials

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.

Webhook Key

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.

Autoconnect Return Data on Sync Webhook

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.

Webhook URL and mock payload data

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.

Example

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.

Regenerating webhook URL

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:

Now when you run this workflow using an older webhook URL link, you will receive an error.

Posting data to webMethods.io Integration via webhook

Let us understand how to pass large data and use it in an action with the help of an example.

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.

Setting parameters through webhooks

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.

Webhook management

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:

Select the required option from the list of options that appear.