Configuring a Webhook with Airtable
Airtable enables you to build and organize databases for just about any project you could imagine. The basic version is totally free to use and allows for real time collaboration with team members, making it an ideal data organization tool.
In the example below, we're using the Call Webhook action in a flow to look up sales agents by zip code as stored in an Airtable database that we've created.
In order to pull data into your flow using a Webhook, you'll first need to create an Airtable account and build your database.
Below is our simple PID lookup database, which includes fields (equivalent to spreadsheet columns) for the contact's name and PID.
After you've created a database in Airtable, you're ready to build your flow. In our example below, we first asked the contact to send their name to look up their PID. By using the Call Webhook action, we will send a request to Airtable to pull in the data from our database.
*Note that look-ups in Airtable are case-sensitive.
First, generate your Call Webhook action:
Next, choose 'GET' and enter your URL and HTTP Headers (see below for more information on where to find this in Airtable).
The components of your encoded URL can be found in your database's API documentation. Locate this documentation by clicking on HELP in the upper right hand corner of your Airtable account. Then, choose "API Documentation":
Then click on the "Authentication" tab to the left of the screen:
On this page, you will find the information you need for your URL, Header Name, and Header Value.
Note that the Header Name is "Authorization" and the Header Value is "Bearer" + your unique API key.
Here's how that looks in the Call Webhook action:
The URL is comprised of two parts.
The first part is provided to you on your Airtable authentication page. In the case of our PID lookup database, the first part is:
https://api.airtable.com/v0/appxhoiUp1L9yAmke/Table%201?
The second part of the URL is a bit trickier, as it is encoded. Here's what it looks like for our PID lookup example:
filterByFormula=Name%3D%22@results.name%22
When decoded, the URL is more readable:
filterByFormula=Name="@results.name"
The pain-free way to create your URL is to simply use our Airtable Webhook Wizard. Here's how that looks:
Enter the following information into the wizard's fields:
Your base ID is found in the API page of your Airtable account. Go to your base, click 'Help' then 'API Documentation' to navigate to this page.
Your airtable base has a name. In our example, it's named 'PID'.
Which columns do you wish to look up? In our PID lookup flow, we're looking up the name of the student, so that is the column header we will enter here.
In this case, we've used 'Equals'. You can also choose to use 'Equals (case-insensitive) to find values that use both capitalized and uncapitalized values such as leah or Leah in our example, or 'Contains' which will find values that include the text of the value, such as Aleah, Maleah, or Leah in our example.
This is the expression of the variable you saved in your flow. It should be written as @results.variable_name. Since we named our collected variable as Name , we'll use @results.name.
If you are looking up a numeric value, be sure to check this box.
Max records refers to the maximum number of Airtable records (fields) you'd like to have returned. If no number is entered, then all records that match your lookup will be returned in your flow.
Once you've entered all the above data, your finished URL will be automatically generated as shown in the red outlined box. That's it!
If you'd rather write your own URL, here's how:
To create the second part of your URL, start with a query string with the field-value pair as follows: filterByFormula=
From there, it's easier to write your URL with special characters and encode it afterwards**.** In the case of our PID lookup, this expression is filterByFormula=Name="@results.name" Here, the first Name refers back to the "Name" field (or column) in the Airtable database, while "@results.name" refers back to the flow variable we saved in our agent look up flow.
When we put it all together, the decoded URL looks like this:
https://api.airtable.com/v0/appxhoiUp1L9yAmke/Table%201?filterByFormula=Name="@results.name"
The last step is to encode the URL. Encoding is necessary as it translates characters into a format that is accepted by web browsers and servers. Use Airtable's URL encoder online, or translate it yourself using a table for character encoding, and here's the final result:
https://api.airtable.com/v0/appxhoiUp1L9yAmke/Table%201?filterByFormula=Name%3D%22@results.name%22
Important note: The character for @ must remain un-encoded!
In the end, this is how the Call Webhook action looks for our PID lookup flow:
Once you've configured your Webhook, you can then use the @webhook.records
variable in your flow, which references variables returned from an external application via a Webhook.
To reference variables from your Airtable database, create a Split by Expression action that evaluates one of the returned values against a response rule.
Here's a look at our Split by Expression action for our agent lookup flow:
A - The operand we used here is the expression @webhook.records because "records" is the key used by Airtable to reference what is essentially a row in our database. You can see the keys for your own database by viewing your Webhook events as detailed here.
B - The response rule has only the phrase works best for this particular use case.
C - This represents the value(s) your response rules will attempt to match against the operand. In this example, we've used [] , which indicates that no matching data was found in our Airtable database.
D - The category in which contacts are placed if the the operand matches the corresponding response rule. Categories are pathways from which connections can be drawn to new nodes, thus directing the contact onward. In this example, because no matching data was found, we want to inform our contact that their lookup did not result in an agent match.
The final piece of the flow is to send our contacts a message returning their PID:
As a reminder, we must use the @webhook.records variable to reference the variables returned from our Webhook. Use @webhook.records[0].fields.name of the field you created in Airtable to reference the variable from your Airtable base.
In our example we used @webhook.records[0].fields.PID to reference the PID. Recall that fields are equivalent to columns in a spreadsheet, which is what we must reference here.
Here is our final result:
We can test our flow using the simulator:
Click on the webhook link in the simulator to view your Webhook event.
For more detailed information about configuring and testing your Webhook, viewing Webhook events, and troubleshooting, click here. If you have any questions, send us a message via the support widget in the bottom righthand corner.
In the example below, we're using the Call Webhook action in a flow to look up sales agents by zip code as stored in an Airtable database that we've created.
Build your Airtable Database
In order to pull data into your flow using a Webhook, you'll first need to create an Airtable account and build your database.
Below is our simple PID lookup database, which includes fields (equivalent to spreadsheet columns) for the contact's name and PID.
Build your Flow
After you've created a database in Airtable, you're ready to build your flow. In our example below, we first asked the contact to send their name to look up their PID. By using the Call Webhook action, we will send a request to Airtable to pull in the data from our database.
*Note that look-ups in Airtable are case-sensitive.
Setting up your Call Webhook Action
First, generate your Call Webhook action:
Next, choose 'GET' and enter your URL and HTTP Headers (see below for more information on where to find this in Airtable).
The components of your encoded URL can be found in your database's API documentation. Locate this documentation by clicking on HELP in the upper right hand corner of your Airtable account. Then, choose "API Documentation":
Then click on the "Authentication" tab to the left of the screen:
On this page, you will find the information you need for your URL, Header Name, and Header Value.
Note that the Header Name is "Authorization" and the Header Value is "Bearer" + your unique API key.
Here's how that looks in the Call Webhook action:
Configuring your URL
The URL is comprised of two parts.
The first part is provided to you on your Airtable authentication page. In the case of our PID lookup database, the first part is:
https://api.airtable.com/v0/appxhoiUp1L9yAmke/Table%201?
The second part of the URL is a bit trickier, as it is encoded. Here's what it looks like for our PID lookup example:
filterByFormula=Name%3D%22@results.name%22
When decoded, the URL is more readable:
filterByFormula=Name="@results.name"
Creating your URL
The pain-free way to create your URL is to simply use our Airtable Webhook Wizard. Here's how that looks:
Enter the following information into the wizard's fields:
Your base ID is found in the API page of your Airtable account. Go to your base, click 'Help' then 'API Documentation' to navigate to this page.
Your airtable base has a name. In our example, it's named 'PID'.
Which columns do you wish to look up? In our PID lookup flow, we're looking up the name of the student, so that is the column header we will enter here.
In this case, we've used 'Equals'. You can also choose to use 'Equals (case-insensitive) to find values that use both capitalized and uncapitalized values such as leah or Leah in our example, or 'Contains' which will find values that include the text of the value, such as Aleah, Maleah, or Leah in our example.
This is the expression of the variable you saved in your flow. It should be written as @results.variable_name. Since we named our collected variable as Name , we'll use @results.name.
If you are looking up a numeric value, be sure to check this box.
Max records refers to the maximum number of Airtable records (fields) you'd like to have returned. If no number is entered, then all records that match your lookup will be returned in your flow.
Once you've entered all the above data, your finished URL will be automatically generated as shown in the red outlined box. That's it!
If you'd rather write your own URL, here's how:
To create the second part of your URL, start with a query string with the field-value pair as follows: filterByFormula=
From there, it's easier to write your URL with special characters and encode it afterwards**.** In the case of our PID lookup, this expression is filterByFormula=Name="@results.name" Here, the first Name refers back to the "Name" field (or column) in the Airtable database, while "@results.name" refers back to the flow variable we saved in our agent look up flow.
When we put it all together, the decoded URL looks like this:
https://api.airtable.com/v0/appxhoiUp1L9yAmke/Table%201?filterByFormula=Name="@results.name"
The last step is to encode the URL. Encoding is necessary as it translates characters into a format that is accepted by web browsers and servers. Use Airtable's URL encoder online, or translate it yourself using a table for character encoding, and here's the final result:
https://api.airtable.com/v0/appxhoiUp1L9yAmke/Table%201?filterByFormula=Name%3D%22@results.name%22
Important note: The character for @ must remain un-encoded!
In the end, this is how the Call Webhook action looks for our PID lookup flow:
Evaluating External Variables
Once you've configured your Webhook, you can then use the @webhook.records
variable in your flow, which references variables returned from an external application via a Webhook.
To reference variables from your Airtable database, create a Split by Expression action that evaluates one of the returned values against a response rule.
Here's a look at our Split by Expression action for our agent lookup flow:
Split by Expression Inputs:
A - The operand we used here is the expression @webhook.records because "records" is the key used by Airtable to reference what is essentially a row in our database. You can see the keys for your own database by viewing your Webhook events as detailed here.
B - The response rule has only the phrase works best for this particular use case.
C - This represents the value(s) your response rules will attempt to match against the operand. In this example, we've used [] , which indicates that no matching data was found in our Airtable database.
D - The category in which contacts are placed if the the operand matches the corresponding response rule. Categories are pathways from which connections can be drawn to new nodes, thus directing the contact onward. In this example, because no matching data was found, we want to inform our contact that their lookup did not result in an agent match.
The final piece of the flow is to send our contacts a message returning their PID:
As a reminder, we must use the @webhook.records variable to reference the variables returned from our Webhook. Use @webhook.records[0].fields.name of the field you created in Airtable to reference the variable from your Airtable base.
In our example we used @webhook.records[0].fields.PID to reference the PID. Recall that fields are equivalent to columns in a spreadsheet, which is what we must reference here.
Here is our final result:
We can test our flow using the simulator:
Click on the webhook link in the simulator to view your Webhook event.
For more detailed information about configuring and testing your Webhook, viewing Webhook events, and troubleshooting, click here. If you have any questions, send us a message via the support widget in the bottom righthand corner.
Updated on: 19/06/2023
Thank you!