Exchanging data with webhooks: POST requests

Unit introduction

You’ve reached the third unit of the “Webhooks” course!

In the previous unit you have seen how data can be sent when calling your webhook, and you have focused on query parameters and the GET request.

Now it is time to focus on POST requests and look into more detail at the body of your request and its structure. You will also have a deeper look at the webhook response.

Time to start!

Element - text / text and image (Portrait) - LARGE

As you’ve seen in the previous unit, you can share data together with your webhook request. Query parameters are used together with GET requests to send query and filter parameters.

For POST requests, you transfer the information using the body, that represents the order slip that you give Walter the waiter containing all the food that you want to eat.

Pro tip: Body indicates the document that you post or return in a request, while payload includes all the data that you send in a request (body, headers and query parameters).

In the advanced course API calls with HTTP modules you will look into the body in greater detail.

For now all you need to know is that you can send data in different formats: raw, JSON, form data, etc and this data will be processed in your request.

Note that all the other HTTP methods like PUT, PATCH and DELETE can be used as well with webhooks, and GET and POST have been used just an example to explain webhook functionalities.

Element - text / text and image (Portrait) - LARGE

You’ve seen in the data structure course that every time data is transferred within Make, it is linked to a data structure that defines how this data is organized.

Think of the data structure like the floor plan of the Tate on me museum: it provides a detailed layout of how different paintings are organized and categorized for easy navigation and retrieval.

This happens for the webhooks as well, where Make automatically determines the data structure when data is sent with the request.

Remember that in the previous unit you have seen that Make can automatically determine the query parameters that are received by the webhook.

Element - Selectable image 3 – modal

When you’re setting up a scenario that contains a Custom webhook module, Make needs to determine the data structure of the payload that is received, together with the request. Let’s learn more about this.

Manuel the Museum creator goes for a walk around the Tate on me museum to see how the work for arts are organized, and draft the plan to represent this.

What is the objective?

Imagine you have just added a webhook in your scenario and you want to set a variable with the data that is received when the webhook is called.

You add a Set a Variable module after your webhook, but you cannot find any field to map.

You haven’t determined a Data Structure, so Make doesn’t know which fields are present in the body and it won’t be able to map them.

The role of the Data Structure is to make the fields of the body available to be mapped in the subsequent modules.

Note: even if the query parameters are not in the Data Structure of the Body, they are also automatically detected by Make and can be mapped in the subsequent modules. Like the data structures, the museum plan lets you know which paintings and sculptures are available on a specific floor and how they are organized.

How is it done?

Make automatically determines the Data Structure using the data that is sent to the webhook.

This means that you need to make a POST request to the webhook with a body that contains the fields you want to include. The data structure is by whom is recognized and determined using this data.

Manuel, the museum curator, is taking a look at the disposition of the paintings and the sculptures, and drafts a floor plan describing their location. It is like taking a look at the paintings and the sculpture you have, and drafting your floor plan that describes them.

You can use Postman as you’ve seen in the previous unit to make a call and send the data. In Postman you can choose and define the body that you are sending with your request.

When you’re sending the data to determine the data structure, your scenario needs to be active. This means it is ready to listen and receive them.

You can do this in three different ways:

1. Click Redetermine data structure This is done from inside the webhook module and no operations are used with this method.
2. Run this module only
3. Run once Both methods consume operations. First you click Run once / Run this module only so the scenario is ready to listen for updates when you make the call using Postman.

   Note: that every time you run your scenario manually the data structure is updated. If you leave your scenario ON and it gets triggered by the calls to the webhook, the data structure is not updated in this case.

What happens when data is shared?

You have just seen that when you select Run once or Run this module only, the data structure is updated in case you send different data.

Once your scenario is built, you need to turn it ON so it will be ready to listen to requests. In this case every time the webhook receives data, it triggers the scenario.

If the data sent is the same as defined by the data structure, all of the elements will be mapped and the scenario executed.

If the data sent has a different data structure, the data structure won’t be updated in this case. The scenario won’t throw an error automatically, but in the event that some parameters are missing, this could lead to an error. You’ll see later how you could enforce the data to have the correct format.

Once the floor plan is ready, Manuel takes a walk through the museum to verify that everything aligns with the layout defined.

Element - text / text and image (Portrait) - LARGE

Let’s test what you have just seen. You will build a simple use case containing a webhook. You will send data to the webhook URL using the POST method, in Postman.

Remember your friend Catherina the Cook who uses a spreadsheet for her restaurant. Hit me with your best pot. She wants to create a webhook so that she can call a URL to add new suppliers to the spreadsheet.

Open the MIC04_U02 spreadsheet created in unit two and add a new sheet called Unit_3. Name the columns Name, Surname, Email, Ingredient.

Note: You will need to create a different sheet, rather than use the one from unit 2. This is because if you add the same ingredient multiple times, it can cause issues with the unit 2 use case, as you would need an aggregator to deal with the output.

Webhooks

This module creates a webhook that you will use to trigger the scenario.

Google Sheets

The module updates your Google Sheet with the information sent to the webhook.

Build the scenario

Let’s build the scenario. Work through each step to continue.

Create the Scenario and Webhook

Create a new scenario and call it MI_C04_U03.

For the first module, add a Custom Webhook as you want your scenario to be able to listen to requests.

After inserting the module, you need to create the webhook. Click Add and call the webhook MIC04_U03_W.

Click Save and see that the module is waiting for data to determine the data structure.

Let’s send the webhook some data! Copy the webhook URL by clicking Copy address to clipboard.

Send Data via Postman

Head over to Postman and create a new request.

Select POST as the method and paste the URL of the webhook you have just copied.

Select Body > Raw and make sure JSON is selected.

In the body copy and paste the JSON document provided:

{
  "name": "Renato",
  "surname": "Risotto",
  "email": "r.risotto@email.com",
  "ingredient": "rice"
}

Click Send to make your request to the webhook URL.

Verify Webhook Data Structure

Go back to Make and see that the Webhook module says Successfully determined.

Your data structure has been determined and it contains 4 elements (name, surname, email and ingredient) all containing strings, like the data you have sent to the webhook.

These elements are now available to be mapped in the subsequent module. Click OK to save the module.

Note: If you want to change your data structure in the future, you can redetermine it and send a request with the new fields contained in the body.

Add Google Sheets Module

Add a Google Sheets → Add a row module to be able to add the data that has been sent to the spreadsheet. You will also be able to see the items available to be mapped.

Connect the module to your Google Account and select the MIC04_U02 sheet. Make sure you select the Unit_3 Sheet Name you have created in this unit.

Under values, click the Name (A) field and you will see that the 4 fields you sent to the webhook are available to be mapped. Map name. Repeat it for surname, email and ingredient in columns B, C, and D respectively.

Click OK to save the scenario.

Element - text / text and image (Portrait) - LARGE

Now that your scenario is ready, let’s test it out by sending some data.

1. Click Run once and see that your scenario is ready to receive the data.
2. Go to Postman and repeat the same request as before by clicking Send.
3. Go back to Make and notice that the scenario has received some data.
4. If you look at the spreadsheet, it has been updated with the information you just sent.

Element - text / text and image (Portrait) - LARGE

As you’ve seen in the previous unit, you can build a response to the webhook request.

You can choose the response you provide to the calling application or scenario. Responses can be used to confirm the receipt of the request, or to provide any relevant data to the caller. You can even decide to send a different response based on the outcome of your scenario.

For a POST request like in this case, a response can be used to notify the user that the update has been successful.

To implement it you will add a webhook response to the scenario you have been using so far.

Let’s see how to do it in the next page.

Webhooks (Custom webhook) → Google Sheets (Add a Row) → Webhooks (Webhook response)

The webhook response module provides the response back to the calling application.

Add the Webhook response module

Let’s add the webhook response to the scenario. Work through each step to continue.

Go to the MI_C04_U03 scenario and add a Webhooks → Webhook response module.

You want to use the response to send a message in JSON format to the calling application to inform Postman that the request has been successful. The message will also include the row number in which the data has been added. Since you are returning a JSON, you will have to specify the format in the headers.

Let’s do it step by step.

Leave the status as 200, and in the Body field copy and paste this JSON string. Map the Row number after the word row and before the ”.

Toggle the Advanced settings to display the Custom headers in which you will specify that the body of the response is a JSON document. Add an item and type content-type in the Key field to indicate that this header will contain info about the type of document that is shared. Under Value type application/json to specify that a JSON document is returned to the calling application. Click OK to save it and save your scenario as well.

Element - text / text and image (Portrait) - LARGE

Now that your scenario is ready, let’s send some data and have a look at the response.

Turn your scenario ON and go to Postman.

Re-send the same data that you have used to determine the data structure.

In the response you will have the information that your request was a success and the row in which your data have been saved.

Great job!

Pro tip: In the next unit you will see that data sent to the webhook can either be immediately processed or saved in the webhook queue and run at a later time.

If the webhook scenario has a webhook response, it has to process the data immediately, as the application that sent the request expects a response back.

In case data is sent to the queue and processed at a later time, you will see a warning in your webhook response module.

Element - Selectable image 3 – modal

Imagine that you want to make sure that the body of the document sent by the caller is in the format you expect, and that all the required fields are present. Can you do it? Of course you can! By adding a data structure in the webhook configuration.

This time Manuel the Museum curator knows exactly how he wants the works of art to be organized in the Tate on me museum, and he draft his plan. Then the paintings are organized in the different rooms following the instructions.

What is the objective?

You might want to ensure that specific fields of your data structure are mandatory and thus always present in your request, and also that no other fields are passed.

With Make you can do that by defining the required fields of your data structure, as well as making it strict: this means it is not accepting other field.

In case a field is missing or an extra one is passed, the scenario won’t be triggered, and no operations will be wasted.

This is also useful to make sure that only intended requests are passed. In this case if a random request is received to your webhook, no scenario is triggered and no operations are consumed.

Note: that enforcing the data structure only works for the payload and not for the query parameters.

Manuel the Museum creator has a vision for Tate on me, and wants the paintings and the sculptures organized in a specific way. He defines the layout of each room: everything he wants needs to be present and no extra elements are allowed.

How is it done?

To enforce the data structure, you need to edit your webhook and toggle Advanced settings.

You can see that you can create or select a data structure.

For each field of your data structure you can select whether they are required or not. If they are required, they will have to be present in the body.

Note that fields have a required parameter, and that the whole data structure has a strict parameter. The first one requires that the corresponding field is mandatory and specified in the body sent to the webhook, while the second one can ensure that no extra field is sent in the body

Note: that strict and required are separate parameters that control different aspects of the body. They require that a required parameter is present and strict that no additional ones are passed.

Manuel precisely writes his requirements specifying which objects to stay in which room and making it very clear that no extra painting or sculpture is allowed.

What happens when data is shared?

Enforcing a data structure ensures that requests only contain all the desired data and no extra fields.

If data is missing or an extra field is added, the body of your POST call will fail the validation and it won’t be sent to your scenario.

Once your scenario is built, you need to turn it ON so it will be ready to process any request sent to the url of the webhook associated with it. In this case every time the webhook receives data, this data will be picked and processed by the scenario

The two advantages of this are that the scenario won’t fail in case some data is missing, and that only the proper requests are passed to your webhook and scenario.

Validation failed for 2 parameter(s): Missing value of required parameter ingredient. Unexpected parameter price found.

Manuel goes and checks that every room is laid out exactly as he wanted. If some paintings are missing, or an extra sculpture is present, he will flag it immediately and it will have to be fixed before the museum begins.

Build it

Let’s enforce a strict data structure in our scenario. Work through each step to continue.

Open the Custom webhook module and click Edit. Toggle Advanced settings. Notice that you can define a data structure? Click Add and name the data structure MI_C04_U03_DS. Add an item and call it name, leave the type as Text and select Yes for Required. Repeat the same for surname, email, and ingredient. This will make sure that each of these items needs to be present in the body. Then select Yes for Strict to make sure no extra data can be passed. Save everything and get ready to test it.

Turn your scenario ON and go to Postman. First send a request with all the expected items in the body: name, surname, email, ingredient. You will receive a 200 status together with the JSON document saying that the request was successful and the row number of the updated record.

Select Run once and then go to Postman to remove the ingredient field from the body of your request. When you send a request you will see a Validation failed message saying that the parameter ‘ingredient’ is missing. If you go to your scenario you’ll see that it hasn’t been triggered. Click Stop to stop the execution of your scenario.

Now let’s add the price field to the body of your request and send it. Because you have enforced a strict body, this time you have an extra validation error that tells you that there is an unexpected parameter. For this reason the request is not passed to your scenario.

Note: If ingredient is not set as a required parameter, the data would have been passed to the webhook URL and the scenario triggered with no validation error.