Webhook

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

What’s an incoming webhook?


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

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


If webhook is switched on for a workflow, Built.io Flow creates a unique webhook URL (for example, https://runflow.built.io/run/abc123) 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 HTTP POST request to Built.io Flow. 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 webhook, 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'. Yo will see the webhook configuration window as shown below:

1-webhook config.png


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 authentication mechanism to your webhook, use the toggle button given beside the ‘Webhook Authentication’ label and and activate it.

2-webhook-auth.png

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 Built.io Flow username and password). For this, simply select 'User Auth' option and provide a username and password of your choice.

3-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 '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://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 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.

4-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 future. Built.io Flow 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_updated.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’. 

5-webhook-test.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 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. 

1.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 'NEXT' button given at the bottom right corner of the webhook configuration window. You will be redirected to 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 Built.io Flow via webhook


You can post large data to Built.io Flow via webhook. Also, you can retrieve this data and use it in your workflow 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 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: 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 ‘NEXT’, test the workflow, and click on 'DONE' and ‘Save’ this workflow.

1.png

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