Webhook

Webhook is one of the many ways to integrate Built.io Flow Enterprise 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. Built.io Flow Enterprise supports incoming webhook.

What’s an incoming webhook?


Incoming webhooks allow external sources to notify Built.io Flow Enterprise about a specific event.

How does an incoming webhook work? How does it notify Built.io Flow Enterprise?


If webhook is switched on for a flow, Built.io Flow Enterprise creates a unique webhook URL (for example, https://runflow.built.io/run/abc123) for that flow. 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 HTTP POST request to Built.io Flow Enterprise. This payload contains the details of the event.

Incoming webhook as a trigger


A webhook can work as a trigger for your flow. To do this, create a flow 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 flow immediately.

So, to summarize, if you create a flow with ‘webhook’ switched on, the flow will run automatically whenever an HTTP POST (with payload) or HTTP GET request is made to the webhook URL. 

To enable webhook, hover over 'Start' button and click on 'Settings' icon or double click on the 'Start' button. From the list of trigger services that appears, click on 'Webhook'. You will see a webhook configuration window as shown below:

incoming-webhook-as-a-trigger

The webhook URL for that particular flow is given on the top of the window. Use toggle button to activate the webhook.

Next, select either 'Basic authentication' or 'Auth Token' method to secure the webhook. Let's understand more about these methods:

Basic authentication


Basic authentication

Adding a Basic Auth means securing your webhook with a username and password (this is not your Built.io Flow Enterprise username and password). For this, simply select 'User Auth' option and provide a username and password of your choice, and click on 'Save'.

basic-authenication

Auth token


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.

Simply select 'Auth Token' option and click ‘Generate Token’ to generate a random auth token (e.g., 6f9a1854848sample663157d1460712634541), and click on 'Save'.

You need to add this token to your webhook URL (?authtoken=TK).

So, your webhook URL, which was earlier https://runflow.built.io/run/abc123 now becomes https://runflow.built.io/run/abc123?authtoken=6f9a1854848sample663157d1460712634541. You can now use your new, secured webhook URL or submit this URL to any external service for triggering a flow.

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

Regenerating Webhook URL


You can also regenerate webhook URL for an existing flow. This ensures that you flow will remain secure even if the webhook URL is compromised. 

To do this, follow the steps given below:

1. Open an existing flow 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. 

5_webhook.png

2. Click on the 'Reset webhook' button given beside the 'Delete' button. You will see that the URL given under 'Webhook URL' field has been changed. 

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

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

Now, when any user tries to run this flow through an older webhook URL link, he will receive an error.

Posting data to Built.io Flow Enterprise via webhook


You can post large data to Built.io Flow Enterprise via webhook. Also, you can retrieve this data and use it in your flow easily.

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

Add ‘Send Email’ action to Built.io Flow Enterprise canvas, and connect it to ‘Start’ and ‘Stop’ to create a flow. Configure the ‘Send 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: Built.io Flow 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 ‘Done’ and ‘Save’ this flow.

posting-data-to-built-io-flow-enterprise-via-webhook

Now, enable 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 authorization you wish to provide. If you have selected 'User Auth' method while activating the webhook, select 'Basic Auth' type from the drop down list and if you have selected 'Auth token' method while activating the webhook, you need not select any 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 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 flow will run automatically. As a result, the recipient (specified in the ‘Send 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://runflow.built.io/run/abc123 and you were trying to pass in the value apple under the parameter fruit. You can do so by running the following Webhook: https://runflow.built.io/run/abc123?fruit=apple. Now, if you want to use this value in any action, simply use {{$request.fruit}} in the given field.