Unit introduction
Welcome to the second unit of the “Webhooks” course!
In the previous unit you have expanded your knowledge on what webhooks are and how they can be used within Make.
In this unit you will learn how to:
- send and receive data to and from webhooks when making a call
- utilize a tool that is used to simulate and test your calls
- build a practical use case containing webhooks
Let’s get started!
Element - text / text and image (Portrait) - LARGE
As you’ve seen in the previous course, webhooks expose a URL generated by Make that waits for other applications to make a request to it.
When you add a webhook to your scenario and schedule it to run instantly, the scenario will be triggered when a call is made to the webhook URL.
It is like your friend Walter the Waiter, in the restaurant “Hit me with your best pot”, who is ready to listen to customer’s requests.
You call Walter over to place your order, and tell him that you are sitting at table 2 and want to eat:
- Stir-fry to Heaven
- Let it Beef
- Total eclipse of the Tart
You are providing him with some information together with your request.
How is this done with webhooks?
Element - Selectable image 3 – modal
You have seen that you can provide Walter with more information along with your request. The same is true for webhooks: there are three different ways to share info when using a webhook.
Query string
You want to pass some key:value parameters that contain information that will be used to modify or specify the behavior of your request, like filtering, sorting or extracting specific data.
The query string comes to the rescue here. It allows you to pass these key:value parameters in the URL of your request. They are used to pass any filtering data.
It is like asking Walter to give us the ‘gluten free menu’ and the ‘wines menu’ before we can choose what meal we want to eat.
Header
In the header you can provide technical information on your request that helps process it. Headers are used to pass metadata and technical information. Metadata is simply “data about data”, e.g the metadata of a webpage can be “title / description / keywords / page author”.
In “Hit me with your best pot” it could be the table number, or the list of ingredients the customer is allergic to, such as ‘lactose’, ‘mango’, ‘nuts’, ‘etc’, so that Catherine the cook knows how to process the meal.
For a webhook, there can be authentication parameters or the content type, which specifies the type of information passed using the body.
Body
The body contains the content of the message that is sent with your request.
It is the order that you place with Walter that contains the food that you want to eat.
In your webhook request, it can be a JSON file that contains information that can be later used in your scenario.
Element - text / text and image (Portrait) - LARGE
The query string is a way of transferring the information in the URL of your request. Let’s have a look at its structure.
https://mywebhook?menu=gluten-free&wine-menu=yes
Webhook
The URL is the webhook generated within Make.
Important: The webhook should be kept secret. Make sure not to embed it into a webpage because if someone finds it, they can use it and trigger your scenario, and consume your operations!
Start of the query string
The start of the query string is always defined by the ? character. It separates the webhook from the parameters that are passed to the scenario with the request.
Key-value pair(s)
It is a set of two linked data items where the key is the parameter name and the value is the parameter’s value, they are separated by an equal sign =. Think of a parameter as a combination that make up a single item of data.
In the example shown here, first parameter contains the menu for gluten free: the key is menu and its value is gluten-free.
For the second parameter, wine-menu is the key and yes the value.
This call says: we want the waiter to bring us the gluten-free menu, as well as the wine-menu.
Parameter separation
It is used to separate multiple key-value pairs, allowing you to pass several parameters in a single URL.
Element - text / text and image (Portrait) - LARGE
We’ve been discussing webhooks, and how they trigger scenarios for a while now. You might wonder, how is a webhook called? Do you remember your old friend HTTP? That’s exactly what you use to call your webhook. As you have seen it in the HTTP course, you can use HTTP to send requests to applications and servers. You can use the same with webhooks, as they are a URL that can be called to request a service. You can see from the set up module that in your request you can add all the elements you have just learned about.
Pro tip in the HTTP to webhook unit you have called a webhook by opening the link in the browser. This is the same of making a GET request.
URL
Here you can add the URL of your webhook.
Method
All of the HTTP methods can be used to call a webhook. You will see different examples of this in this course.
Headers, Query String, and Body Type
These are the three ways to send information with your request that you have just explored.
Element - text / text and image (Portrait) - LARGE
When you make an HTTP call, you will receive an answer from the server together with a status code.
The same happens when you call a webhook.
The default answer that you get from Make is status 200 and a string that says Accepted.
Must be higher than or equal to 100.
This response can be modified and customized as well, and you will learn how to do that when building the different use cases.
For now you just need to know that you can define the status, the body, and the header of the response. For example, you can use the header to specify that a JSON file will be returned, and send the JSON file in the body of the response.
Element - text / text and image (Portrait) - LARGE
You have seen that an HTTP call needs to be made in order to call your webhook and trigger your scenario.
To do so, you can use a scenario with the HTTP → Make a request module, where you will use the URL of your webhook and the different parameters. Then you will have to run it in order to call your webhook.
However, the best practice when testing HTTP calls is to use a tool called Postman. It will make your life easier!
Postman is a free platform that allows you to set up and test HTTP calls. You can define all the parameters of your call and receive the application response.
You will use it to test the HTTP calls in your use case. Head over to the Postman website and sign up to create your free account. You will learn how to use it when building your scenario.
Note: that other tools are available as well, like Insomnia, Taled API tester, cURL, HTTPie, etc
Element - text / text and image (Portrait) - LARGE
Catherine the Cook has a list of suppliers for her restaurant. She has saved their contact details in a Google Sheet.
Hit me with your best pot
When planning her shopping, she wants to search for the ingredients she needs and retrieve the contact details of the dedicated supplier.
To do so she will create a scenario that searches the Google Sheet and retrieves the data she needs.
The scenario is associated with a webhook that can be called to start it. Think of the webhook as an API endpoint, and the associated scenario as the service that processes the request.
The HTTP call to trigger the scenario can be made by another scenario containing an HTTP → Make a request module, or Postman. We will use the latter in this case.
Scenario overview
Let’s see what Catherine’s scenario will look like.
Webhooks → Custom Webhook
This module is where you create the webhook that will listen to requests from other applications or scenarios.
You will search for the contact that provides a specific ingredient using the Google Sheets → Search Rows module. The ingredient used for the search is passed as a query parameter when the webhook is called.
When setting up the module, you will make sure that the query parameter is present in your request.
Google Sheets → Search Rows
The query parameter sent to the webhook is used to search for the corresponding row in the Google Sheet.
If found, the full line with the contact details is output as a bundle.
Router
Two cases need to be taken into account:
- the ingredient is found and the whole row is returned
- no item is found
A Router is used to separate the two cases and a Filter is used to process the data according to the two cases.
JSON → Create JSON (Match Found)
The output of the row identified is converted into a JSON file.
Note that a filter is used before the module so that only the bundles that contain data are passed through this route.
Webhooks → Webhook response (Match Found)
The JSON file is sent back as a response to the application that called the webhook URL.
Webhooks → Webhook response (Match Not Found)
In case the ingredient is not found in the Google Sheet, the webhook response is used to inform the caller.
Element - text / text and image (Portrait) - LARGE
Before you start building the scenario you need to prepare the Google Sheet where Catherine stores all of her suppliers details.
To do so, create a new Google Sheet on your Google Drive and call it MIC04_U02.
The columns must be named Name, Surname, Email, Ingredients.
Fill it in as shown in the picture. You can copy and paste this information here. Ensure you paste it into cell A:1.
Important: Make sure that only one ingredient per type is present in your spreadsheet. If an ingredient is present more than once, the output of the Search will contain multiple bundles and an aggregator needs to be used to deal with the results. The objective of this use case is to demonstrate the usage of webhooks, and for this reason we kept it simple and didn’t add an aggregator.
How to use Postman
You will use Postman while building and testing your scenario, so let’s have a look at the different components of its interface.
HTTP Methods
The GET button allows you to select the HTTP method for your request. Common methods include GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS.
URL Input
This is where you add the URL that you want to make your HTTP call to.
Query Parameters
Under the Params tab, you can specify query parameters using key and value pairs.
Headers
Under the Headers tab, you can specify headers using key and value pairs.
Body
The Body tab is for the body of the request. Note that different kinds of body types can be specified. You will learn about them in the Advanced course.
Response
In this space, you will see the response of your call. In this example, the default webhook response is displayed. You can see the 200 OK status with the Accepted string.
Build the scenario 1/3
Now that you have everything ready, let’s start building the scenario. Work through each stage before you continue.
Create the Webhook Module
Create a new scenario and call it MI_C04_U02.
Add a Webhooks → Custom webhook module. As you’ve seen in the previous unit, you need to create the webhook from this module. Ensure that you don’t select Custom mailhook!
Click Create a webhook. Click Add besides the ‘Webhook’ field, and in the “create a webhook” pop-up, call your webhook MI_C04_U02 and click Save.
This module is waiting for a call to the URL of the webhook to determine the structure of the data that are passed through with the call.
In the Webhooks form you can see that there is a red box listening to any data coming in to be able to determine the data structure. Click Copy address to clipboard to copy the webhook URL and let’s make a call to determine the data structure with Postman.
Configure Postman
Go to the Postman website and log in with your credentials.
From the Workspaces menu to the left select My workspace.
Click on the + symbol next to Overview to create a new request. If this is your first time in Postman, you may see Overview/Getting started tab here too.
With Postman you can set up all the parameters for your HTTP call. Let’s have a closer look at them.
Make the Call and Determine Data Structure
Let’s use Postman to make a call to the URL of your webhook and define its data structure.
First paste the webhook in the URL field and leave GET as the method, since you would want to get some information from your scenario.
In your request you will pass the ingredient parameter in the query string. To define the query parameters, navigate to the new row under Query Params. Type Ingredient under Key and test under Value.
Note: that this call is used just to define the structure of the call, so any value can be used in the query parameter value. Ensure that you have saved your scenario in Make before the next step! Within Postman, click Send to send your request to your webhook in Make. In the response area you can see
status 200and the Make defaultAcceptedstring. While in Make you can see that the Data structure has been successfully determined. The Webhooks module will show “Successfully determined” once the data structure is received. Click OK to save the module.
Understanding Query Parameters
The presence and the structure of the query parameters can be automatically determined by Make when a call is made, but there isn’t a way of manually defining the structure.
This means that you cannot make a specific query parameter required i.e. your call always has to contain an Ingredient parameter. If for example in the query parameters the parameter Ingredient is missing, and the Amount parameter is present, your request will still be processed and the data passed to your scenario.
In this case it could be possible that the scenario will throw an error if a parameter is missing or do not return any data.
Note: that query parameters are usually only present in GET requests. You will use them to specify parameters that are used to filter the data that are retrieved.
Build the scenario 2/3
You have created your webhook and determined the data structure. Work through every step to continue building your scenario.
Search for the Ingredient
You need to search for the ingredient specified in the call in your Google Sheet.
To do so add a Google Sheets → Search Rows module. Connect it to your Google account and select the MLC04_U02 sheet that you have previously created.
Select Sheet1 under Sheet Name.
In the filter section select Ingredients (D) from the dropdown menu. Leave the operator Text operator: Equals to and map the Ingredient item from the webhook in the field below.
Click OK to save it.
The module will use the value of the ‘ingredient’ query parameter that is passed to the webhook URL to search the Ingredient column and return the row information if there is a match.
Route the Scenario
Add a Router to be able to handle the two cases:
- In this example, the information picked from the found row will be used to create a new JSON document, and returned as the answer. The filter sends all the bundles that contain a match along this route.
- The search doesn’t find a match. In this case the response contains a string saying that no match has been found.
Pro tip: the second route will be the fallback route. It is the route that catches all requests that don’t match any of the other defined routes, typically used to handle 404 status messages.
Create the JSON Document
If a match is found, the data from the found row are used to create a new JSON document.
Add a JSON → Create JSON module to the upper route. The first thing to do is to define the data structure that your data will follow. The data structure describes how the JSON data is organized and enables mapping individual JSON items to other modules in your scenario.
You want to organize the information that are in the spreadsheet (Name, Surname, Email, and Ingredients) in a single collection.
To do so, click Add under Create a data structure. It will open a new window - call it ML_C04_U02.
Click Add an item and call it contact and as a type select Collection from the drop down menu.
The collection will contain all the contact details of the providers (name, surname, email, and ingredient) and you define them in your data structure. To do so specify the name and the data type of every item. The data type is Text for all four of them.
Add an item and call it name. Leave Text as the type and all the other parameters as default.
Repeat the same process for surname, email, and ingredients.
When you’ve done click Save to save your data structure. You will see that the items that you have just defined, appears in the Create JSON module now.
Now you need to map the items from the Google Sheet that are output in the Search rows module to the corresponding items that you have just created in the JSON module.
For example under name, map Name (A) from Google Sheets.
This way the information of every retrieved row will be organized in your JSON.
To change the format of this output from a single line of JSON, to Pretty-Printed, toggle advanced settings and under Indentation, select 1 tab. Pretty-printed means that the JSON will be organized and more readable!
Once you’ve mapped all the four items, click OK to save the module.
Respond with JSON
You want to send the JSON document that you have just created in the response of your webhook. To do so add a Webhooks → Webhook response module after the JSON module.
Leave the status as 200 and in the body field map the JSON string you have created in the previous module.
You need to specify in the headers that your response contains a JSON string. Add a header items and in the Key type content-type to indicate that this header contains information on the file that is returned. As the Value type application/json to specify the type of the file that is passed. Note to press Esc after typing / to close the pop-up window and continue typing JSON.
All set. Click OK to save it.
Build the scenario 3/3
Let’s finish setting up the scenario by handling the routes and the webhook responses. Work through every step to finish building your scenario.
Set up the “match found” filter
To make sure that only when a match is found the bundle is passed through the route that you have just defined, you need to add a filter.
Click on the link between the Router and the Create JSON modules to open the filter set up.
Call the filter match found and map the Total number of bundles from the Search rows module in the Condition field.
For the operator select Numeric operators: Not equal to and type 0 (number, not letter) in the box below. This ensures when there is a match between the query parameter ingredient and items in the Ingredient column, at least a bundle is returned. The filter ensures that only when there is a match, the bundle proceeds through the route. Click OK to save the filter.
Add the “match not found” Webhook response
For the other route add a Webhooks → Webhook response module.
In the status field type 404 and in the body add the string Not found.
You want to pass it as plain text and to do so toggle Advanced settings to add this information in the header.
Add an item and type content-type in the key and text/plain in the value to specify that the body has to be transferred as plain text.
Click OK to save it.
Configure the “match not found” route as fallback
Let’s sort the filter for this route. Click on the link between the Router and the Webhook response you have just added and the filter window appears.
Call it match not found and select Yes to Set this route as fallback.
This way it will be used for all the data that does not go through the other route.
Click OK to save it. Make sure you save your scenario too.
Pro tip: You can label the order of the routes and the fallback route in your scenario. To do so right click in the scenario and select Show route order. You will see 1st and fallback before the route name.
Test the scenario
Your scenario is ready time to test it out. Work through each step to continue.
Go to Postman and load the request that you have set up previously. In the query parameters, change the test value to Cheese and click Send.
You can see that you get 200 OK status and the standard Accepted response. This is weird, you would have expected one of the responses that you set up in the scenario, right?
Let’s go to the scenario and have a look at what happened. The scenario is turned OFF, that’s why! Even if you made a request, the scenario wasn’t active and it was not triggered.
Make sure that your scenario is turned ON and scheduling is set to Immediately, and click Save. Click Run once. You get a pop up saying there is unprocessed data in the webhook queue. It is the data that you just sent, but it was not processed because the scenario was off.
Click Use existing data. You get two warnings this time! What is happening?
Response can’t be processed when scenario is not executed immediately on data arrival. Origin Make Webhooks Webhook response
The warning tells you that the response can only be processed immediately as soon as the request is sent. You will learn more about this and webhook queues in the next units, but for now what you need to remember is that the scenario needs to be active when you send a request.
Turn ON your scenario. You have to choose when to run the scenario - select Immediately. Click Save. Then send the same request again with Postman.
Now we’re talking! Within Postman you will see you receive a 200 OK status and the JSON file with the contact of the supplier providing cheese. Catherine is happy and can now order everything more efficiently, making sure Hit me with your best pot has all the ingredients they need!
Test the Fallback Route
Let’s change the request and add an ingredient that is not on the list and see what happens. Make sure your scenario is still on. Go to Postman, change Cheese to Pizza and click Send.
Nice, you got the Not found message! Your scenario was triggered and your data went to the fallback route since no match was found for the ingredient Pizza!
Nice job! Turn off your scenario to ensure you don’t end up accidentally using operations.
Element - text / text and image (Portrait) - LARGE
Earlier you have seen that metadata can be passed using headers.
You can send technical information like, for example, size of the request, cookies, format of the body, expected format, type of compression, etc.
Headers also provide more confidentiality because they are not visible in the URL and do not have a limitation in the number of characters unlike query parameters.
To be able to map these items in the subsequent modules, you need to add the headers to the output of the custom webhook module.
To do so click on your Custom webhook module and Edit your webhook.
Toggle the Advanced settings and select Yes for Get request headers. Now the headers are passed as the output and you can map it in the next modules if needed.
You will learn how to use headers in the Advanced courses.
For more information on how to create a webhook in Webhooks, see the online Help.