Webhook

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 appears, click on Webhook. You will see the webhook configuration window as shown below: 

webhook.jpg


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 also add an extra layer of security to your webhook by enabling webhook authentication. Let’s understand how it works.

Webhook Authentication

To add an authentication mechanism to your webhook, use the toggle button given beside the Webhook Authentication label and activate it.

There are two ways to add authentication to your webhook:

1. User Auth

2. Auth Token


1. User Auth

User auth is the basic authentication which consists of a username and password (this is not your webMethods.io Integration username and password). For this, simply select User Auth option and provide a username and password of your choice.

user_auth.PNG

2. Auth token

You can alternatively use auth token to secure your webhook. This token becomes part of your webhook URL, and acts as a unique identifier, when submitting to any external service.

To do this, select the Auth Token option and click GENERATE TOKEN to generate a random auth token (e.g., 6f9a1854848sample663157d1460712634541)

You need to also add this token to your webhook URL (?authtoken={token}).

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 external service for triggering a workflow.

Since the new token is only known to you, it creates an extra layer of security for your webhook. You can change the token any time by clicking GENERATE TOKEN Your webhook URL will change accordingly.

auth_token.PNG

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 the future. webMethods.io Integration uses this data to display the output of the webhook in the subsequent actions of your workflow.  

To add webhook payload, enable the Webhook Payload option using the toggle button.

webhook_payload.PNG


You will see three text fields: Headers, Body, and Query. These are the keys that are returned in the output of the webhook.

Enter the payload data (in JSON format) in the relevant fields. 

Once you have added required settings for authentication and payload, click on Next

webhook_configure.PNG

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. 

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 steps given below:

1. Open an existing workflow of which webhook URL you wish to reset and double click on Start icon (which now shows the webhook icon). A webhook configuration window will appear.To do this, follow the steps given below:

regenerating_webhook_URL.jpg

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

3. Click on the Next button given at the bottom right corner of the webhook configuration window. You will be redirected to the canvas. 

4. Save the workflow. This will enable the regenerated webhook URL for your workflow. 

Now, when any user tries to run this workflow through an older webhook URL link, he 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.

Add Send an Email action to 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, please ensure to enter the key name in lowercase. For example, if the actual header key is Name, please 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 on Next, test the workflow, and click on Done and Save this workflow.

39-webhook.png



Now, enable the webhook as shown in the above step. You can use this webhook URL with any REST API client (such as Postman) to post data.

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 to 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 the JSON format. Once you are done with this, click on Send located on the top right corner of the page.

postman-image

As soon as you hit the Send button, 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).

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 were trying to pass in 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, simply 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 steps given below:

Step 1: Navigate to the project which contains the workflow of which webhook settings you want to update.

40-webhook-proj.png

Step 2: You will be redirected to the selected project where you can see the project settings options along with the workflow cards. Click on the Configuration tab.

41-set-webhook.png

Step 3: You will be redirected to the configurations page where you can see the webhooks, accounts, triggers, and parameters associated with the selected project. Click on the Webhooks tab to view and manage your project webhooks.

42-webhook-edit.png

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.

43-webhook-final.png

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. Select the authentication method you would like to use, and configure it as you would normally do. Read more about adding webhook authentication.

View Payload: When you click on this option, you will be able to view the webhook payload. However, in order to modify it, you will need to navigate to the workflow and modify it through the canvas.