Webhook

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.

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

Webhook Authentication

You can secure your webhook data by using Auth Tokens. To do so, switch-on the Webhook Authentication toggle button.

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.

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.

To configure webhook payload , click on the Next button.

You will see 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: While configuring the request, please 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. 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 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.

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:

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.

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