Learn to Build Powerful API Endpoints Using Webhooks 🧰
What are webhooks?
Webhooks listen for a request and receive data when an event occurs. This reminds me of myself as a kid, waiting for the school bell to ring. When the bell rang, my workflow in life was to run home for a snack! Webhooks work in a similar manner; they are triggered by events — making webhooks an excellent way of receiving and returning data, as they are very efficient and fast, eliminating the need for maintaining a client state (such as a timestamp, for example) that would be necessitated in a polling-based setup.
The Webhook node is a versatile and powerful node in the n8n ecosystem. It receives HTTP Requests, instead of sending them. This makes the node useful — you guessed it, to receive data from any other service that supports Webhooks.
The Webhook node is a Trigger node, which means that it serves as the starting point for an n8n workflow. This allows several different services to connect to n8n and run a workflow when data is received. We can use Webhook nodes in workflows where we want to receive data and run a workflow based on the data. The Webhook node also supports returning the data generated at the end of a workflow. This makes it very useful to build a workflow to process data and return the results, for example.
In this article, we are going to explore three examples and dive into how the Webhook node can be used in your workflows to trigger them and help automate tasks:
- We will take a look at how to receive and return data via a Webhook node by getting information about the weather for any city. You can find the workflow on the workflow page on n8n.io.
- We will determine how to use authentication in the Webhook node by storing and sending information about the weather for any city via SMS. You can find the workflow on the workflow page on n8n.io.
- We will learn how to receive files and binary data using the Webhook node by detecting, storing, and returning the information about a purchase from the image of a receipt. You can find the workflow on the workflow page on n8n.io.
Getting Ready
Setting up n8n
This tutorial assumes that you have n8n up and running. In case you don’t, you can get started by following the instructions on the Quickstart page. You can also sign-up for n8n.cloud to get access to our hosted service. (All the workflows created in this article use n8n@0.103.1)
Understanding The Various Parameters Of The Webhook Node
Authentication: The Webhook node supports two methods of authenticating a request that it receives.
- Header Auth — A method of authentication where the specified header parameter must be passed along with the request. This method can be used when you want to authenticate using an API key or an access token, for example.
- Basic Auth — A method of authentication where the specified username and password must be passed along with the request.
HTTP Method: The Webhook node supports receiving two types of HTTP Requests.
- GET Request — GET requests are typically used to request data from a resource. This type of request is typically used to retrieve data from a service.
- POST Request — POST requests are typically used to send data to a resource for a create/update operation. This type of request is typically used to send data to a service.
Path: By default, this field contains a randomly generated webhook URL path, to avoid conflicts with other Webhook nodes.
- You can manually specify a URL path if necessary. A good example would be if you were using n8n to prototype an API; and wanted consistent endpoint URLs.
Response Code: Allows you to customize the HTTP response code that the Webhook node will return upon successful execution.
Response Mode: This dropdown list allows you to select between two response modes.
- On Received — When this option is selected, the Webhook node will return the specified response code along with the message “Workflow got started.”.
- Last Node — When this option is selected, the Webhook node will return the specified response code along with the data output from the last node executed in the workflow.
Optional Parameters: The Webhook node also supports several optional methods that can be used during configuration.
- Response Headers — This option allows you to specify additional headers in the Webhook response.
- Raw Body — This option is used to specify when the Webhook node will receive data in a RAW format, such as JSON or XML.
- Binary Data — This option is available only when the Webhook node is set to receive POST requests. Setting this to ‘true’ lets the Webhook node know that it will receive binary data (such as an image/audio). You can use this option when you expect to receive a file via your Webhook node.
Conditional Parameters: The Webhook node also supports several other parameters, that are used only in certain configurations.
- Response Data — This option is available only when the Response Mode is set to ‘Last Node’. It allows you to choose which data to return.
- All Entries — Choose this option to return all the data generated by the last node in the workflow, as an array.
- First Entry JSON — Choose this option to return the first data entry of the last node in the workflow, as a JSON object.
- First Entry Binary — Choose this option to return the binary data of the first entry of the last node in the workflow, as a binary file.
cURL
We will be using cURL to send requests to our Webhook nodes throughout this tutorial. If you do not already have cURL, you can find instructions to install and use cURL in this guide.
Using with the HTTP Request node
In this article, we will connect to Webhook based workflows via cURL requests. However, a far more interesting proposition would be to use the HTTP Request node to connect to the Webhook node and send requests.
You could build several of these Webhook based workflows to support a main workflow, powered by HTTP Request nodes. As a starting point, here’s a video that demonstrates how you can send a request to your Webhook based workflows using the HTTP Request node.
A quick note about Webhooks in n8n
Tunnels in n8n
Does not apply to n8n.cloud users, feel free to skip this section.
To be able to use webhooks, n8n has to be reachable from the web. To make that easy, n8n has a tunnel service, which redirects requests from our servers to your local n8n instance, in case you do not have it self-hosted on a server.
If you choose to not use the tunnel service, keep in mind that your cURL requests must be sent from the machine that n8n is running on.
To enable and use this tunnel service, simply start n8n with the --tunnel option.
Please note that the tunnel is for testing purposes only and should not be used in production.
If you installed n8n with npm, this would be:
n8n start --tunnelIf you’re running n8n in Docker, this would be:
docker run -it --rm \
--name n8n \
-p 5678:5678 \
-v ~/.n8n:/root/.n8n \
n8nio/n8n \
n8n start --tunnelProduction vs. Test URLs
Every Webhook node in n8n has two types of URLs — Test and Production. The test URLs are for use when building the workflow, it listens for 120 seconds after the Execute node button is clicked and displays the received data directly in the Editor UI, making it useful to sample your data during the build process.
The production URL listens continuously once the workflow is activated and does not display the data received in the Editor UI, but instead executes the workflow directly. You can review the data generated during production executions by clicking on the ‘Executions’ tab in the left sidebar. You can specify which kinds of execution history to save in the ‘Settings’ tab in the left sidebar, under the ‘Workflows’ dropdown list.
For the purposes of this article, we assume that every webhook request uses the test URL; but if you plan on deploying this workflow for regular use, you will have to create the workflow, use the production URL, and activate the workflow.
Here is a video of me demonstrating how to retrieve the production and test webhook URLs in n8n:
Workflow 1 — Get information about the weather for any city
For this example, we will be retrieving the information about the weather in a city using the OpenWeatherMap node and returning the temperature, humidity, wind speed and a short description of the weather.
You can also follow along this example by copying the workflow from n8n.io and making appropriate changes at each step.
1. Webhook node: Receive GET requests
First, click on the + button on your n8n dashboard, select the Trigger tab and type “Webhook” into the search box and select the Webhook node. Then, select Last Node for Response Mode. This will return the data from the last node of the workflow as the Webhook response. Finally, select All Entries for Response Data. This tells n8n to return all the data generated by the last node of the workflow in the response.
Now let’s save our workflow to register the webhooks, then click the Execute Node button and send your cURL request.
Let’s send it some data using a cURL request, remember to change the URL to your test webhook URL from n8n:
curl --location --request GET 'https://your-n8n.url/webhook/path' --form 'city=bangalore'You should see the data in the Webhook node, similar to this:
2. OpenWeatherMap node: Get weather information
Next, add an OpenWeatherMap node and connect it to the Webhook node. Configure your OpenWeatherMap credentials by following the instructions here. Note that it might take up to two hours for your OpenWeatherMap API key to get activated. Select Metric for Format (unless you live in the US, Liberia or Myanmar 😉). Click on the gears icon next to the City field and use the variable selector to select the city from the Webhook node’s output data for City. You can do this by going to Current Node > Input Data > JSON > body > city.
Now, click on the Execute Node button and you should see the weather information retrieved from OpenWeatherMap like this:
3. Set node: Create response message
Finally, add a Set node and connect it to the OpenWeatherMap node. Execute the OpenWeatherMap node to load the data into n8n. Set the Keep Only Set toggle to ‘true’. This tells n8n to only return the data specified in the Set node. Select ‘String’ from the Add Value dropdown list and enter ‘humidity’ as the name; use the variable selector to select the humidity value from the OpenWeatherMap node’s output data for value. Similarly, add entries for temperature, wind speed, description and city.
Now, click on the Execute Node button and you should see the data from the Set node like this:
When you’re done, your workflow should look like this:
Now click on Execute Workflow and test it by sending a cURL request similar to the one above, you should get a response like this:
[
{
"tempC": 25.92,
"humidity": 88,
"windspeed": 2.09,
"description": "mist",
"city": "Bengaluru, IN"
}
]Here’s a video of me building this workflow, for reference:
Workflow 2 — Storing and sending information about the weather for any city via SMS
For this example, we will be receiving a query, saving the details of the query in Airtable, retrieving the information about the weather in a city using the OpenWeatherMap node and sending an SMS of the weather information.
You can also follow along this example by copying the workflow from n8n.io and making appropriate changes at each step.
1. Webhook node: Receive POST requests
First, click on the + button on your n8n dashboard, select the Trigger tab and type “Webhook” into the search box and select the Webhook node. Select Header Auth from the Authentication dropdown list. Select/Create new Header Auth credentials in the Credentials section by entering and saving a name and value. Then, select the POST option for HTTP Method. This tells n8n to listen for a HTTP POST request instead of the default GET request. Then, select On Received for Response Mode. Select ‘Raw Body’ from the Add Option dropdown list and set the toggle to ‘true’. This lets n8n know that we are sending RAW data.
Now let’s save our workflow to register the webhooks, then click the Execute Node button and send your cURL request.
Make sure it works by sending it some data using a cURL request, remember to change the URL to your webhook test URL from n8n:
curl --location --request POST 'https://your-n8n.url/webhook/path' \
--header 'apikey: your-api-key' \
--header 'Content-Type: application/json' \
--data-raw '{
"name":"YourName",
"number":"+919876543210",
"city":"CityName"
}'You should see the data in the Webhook node, similar to this:
2. Set node: Extract requester data
Next, add a Set node and connect it to the Webhook node. Set the Keep Only Set toggle to ‘true’. This will keep only the values you specify in this node, helping save them in an Airtable in the next step. Select ‘String’ from the Add Value dropdown list and enter ‘Name’ as the name; use the variable selector to select the name value from the Webhook node’s output data for value. Similarly, add entries for number, and city.
Now, click on the Execute Node button and you should see the data from the Set node like this:
3. Airtable node: Save requester data
Copy this table to your Airtable account. Add an Airtable node and connect it to the Set node. Configure your Airtable credentials by following the instructions here. Set Append as the Operation. Enter your Airtable Application ID (you can find the app ID by going to https://airtable.com/api and selecting the base) in the Base ID field. Enter “Table 1” in the Table field.
Now, click on the Execute Node button and you should see that the data is saved in Airtable like this:
Here’s a picture of the table I used for this workflow:
4. OpenWeatherMap node: Get weather information
Next, add an OpenWeatherMap node and connect it to the Airtable node. Configure your OpenWeatherMap credentials by following the instructions here. Click on the gears icon next to the City field and use the variable selector to select the city from the Webhook node’s output data for City.
Now, click on the Execute Node button and you should see the weather information retrieved from OpenWeatherMap like this:
5. Twilio node: Send SMS containing weather information
Finally, add a Twilio node and connect it to the OpenWeatherMap node. Configure your Twilio credentials by following the instructions here. Use the variable selector to select the number field from the Webhook node’s output data for the To field. Similarly, use the variable selector to write a short message about the weather using the information from the OpenWeatherMap node for the Message field.
Now, click on the Execute Node button and you should see that a message is sent using the Twilio node, like this:
When you’re done, your workflow should look like this:
Now click on Execute Workflow and test it by sending a cURL request similar to the one above, you should see the data from your request get added to Airtable, and you should receive an SMS on your phone like this:
Here’s a video of me building this workflow, for reference:
Workflow 3 — Detect and store the information about a purchase using the image of a receipt
For this example, we will be receiving an image via the Webhook, and then using the Mindee node to read and extract data about the purchase, saving the data in Airtable and also returning the data.
You can also follow along this example by copying the workflow from n8n.io and making appropriate changes at each step.
1. Webhook node: Receive images via POST requests
First, click on the + button on your n8n dashboard, select the Trigger tab and type “Webhook” into the search box and select the Webhook node. Select Header Auth from the Authentication dropdown list. Select/Create new Header Auth credentials in the Credentials section by entering and saving a name and value. Then, select the POST option for HTTP Method. Then, select Last Node for Response Mode. Select All Entries for Response Data. Select ‘Binary Data’ from the Add Option dropdown list and set the toggle to ‘true’. This lets n8n know that we are sending a file.
Now let’s save our workflow to register the webhook, then click the Execute Node button and send your cURL request.
Make sure it works by sending it some data using a cURL request, remember to change the file path to your image file and the URL to your webhook test URL from n8n:
curl --location --request POST 'https://your-n8n.url/webhook/path' \
--header 'apikey: your-api-key' \
--form 'receipt=@/path/to/receipt.jpg'Notice that this cURL request contains a path to an image file that is our receipt. This is the receipt that I used to test my workflow, although you can use one of your own!
You should see the data in the Webhook node, similar to this:
2. Mindee node: Detect transaction information
Next, add a Mindee node and connect it to the Webhook node. Configure your Mindee credentials by following the instructions here. Enter ‘receipt’ in the Binary Property field. This tells the Mindee node which field of the Webhook node’s output contains the image file that needs to be processed.
Now, click on the Execute Node button and you should see the extracted information retrieved from Mindee like this:
3. Airtable node: Save extracted information
Copy this table to your Airtable account. Add an Airtable node and connect it to the Mindee node. Configure your Airtable credentials by following the instructions here. Set Append as the Operation. Enter your Airtable Application ID in the Base ID field. Enter “Receipt” in the Table field. Set the Add All Fields toggle to ‘Off’. Then, click the Add Field button and enter ‘category’ in the newly added Name field. Similarly, create entries for ‘date’, ‘currency’, ‘locale’, ‘merchant’, ‘time’, and ‘total’ under the Fields section.
Now, click on the Execute Node button and you should see that the data is saved in Airtable like this:
Here is a picture of the table I used in this workflow:
4. Set node: Create response message
Finally, add a Set node and connect it to the Airtable node. Set the Keep Only Set toggle to ‘true’. Select ‘String’ from the Add Value dropdown list and enter ‘data’ as the name; use the variable selector to select the fields returned from the Airtable node’s output data for value. Similarly, add a string field with the name ‘message’ and use the variable selector to write a short message about the transaction using the information from the Mindee node.
Now, click on the Execute Node button and you should see the data from the Set node like this:
When you’re done, your workflow should look like this:
Now click on Execute Workflow and test it by sending a cURL request similar to the one above, you should get a response like this:
[
{
"data": {
"category": "miscellaneous",
"date": "03-09-2020",
"currency": "EUR",
"locale": "de-DE",
"merchant": "REWE",
"time": "12:22",
"total": 2.6
},
"message": "You spent EUR 2.6 on miscellaneous at REWE on 03-09-2020 at 12:22"
}
]Here’s a video of me building this workflow, for reference:
Further exploration
Many online services support Webhooks, and you can use n8n to integrate with any of these platforms using a similar set of steps.
With the Webhook node, you can also use n8n to trigger event-based workflows. This opens up a lot of possibilities as n8n’s open, cross-platform nature allows integration of multiple platforms into a single workflow.
For example, the data extracted from the receipt could be added to Zoho Books or Xero for accounting by adding a node to the workflow. The weather data obtained from OpenWeatherMap could be connected to Twitter to respond to tweets, or Philips Hue, to change the colour of a light according to the outside temperature!
For more cool ideas on how n8n can be used, check out our blog.
Conclusion
In this tutorial, we learned to leverage the Webhook node to get weather data, send weather updates over SMS and read data from the image of a receipt. We also discussed the potential ways the Webhook node can be used in other workflows and how powerful the Webhook node can be in event-based workflows.
Every person has their own set of preferred tools and processes. n8n helps you automate your workflows, regardless of how many different tools you use. We connect every tool with every other tool, making n8n work for you, rather than the other way around, like some others.
What will you automate?
In case you’ve run into an issue while following this tutorial, feel free to reach out to me on Twitter or ask for help on our forum 💙
