How to use webhooks

Webhooks is a mechanism used in web development to enable one system or application to send real-time data to another system or application whenever a certain event occurs. It allows for the automatic transmission of information between systems without requiring constant polling or manual intervention.

Retable's Webhooks allows you to be notified in real-time about changes in your projects, from new records to a column being updated in an existing row, to a row moving in or out of a view.

Webhooks provide you with a streamlined approach to managing various API workflows. In essence, working with APIs entails one software system requesting specific information from another, typically through a GET request. This mechanism proves efficient when an application routinely retrieves data from Retable's APIs to gain insights into table or base statuses. However, the process can become somewhat laborious when aiming to maintain real-time information accuracy, especially as new records are added, existing ones updated, or some removed. Often, the act of fetching data via GET from Retable results in surplus calls that yield no substantive changes from previous requests.

Enter webhooks—an elegant solution. These enable the source application, like Retable in this context, to initiate a POST request to the destination application where the information will be utilized. This innovation circumvents unnecessary API calls since the POST request materializes solely based on the predefined specifications of the webhook.

Do you want to skip the introduction part and learn how to start with Webhooks?

Fundamentals of Retable's Webhooks

Webhooks are an action type that you can send an HTTP request in case an automation is triggered.

Http Methods

HTTP methods are an integral part of the Hypertext Transfer Protocol (HTTP), which is the foundation of data communication on the World Wide Web. In the context of webhooks, HTTP methods determine the type of action to be performed on the resource located at the URL endpoint provided by the listener (subscriber) when an event occurs. Here are 4 HTTP methods used in Retable's webhooks:

GET: While less common in webhooks, some systems might use GET requests to deliver event information. However, using GET requests for webhooks can have limitations in terms of security and data size, as GET requests typically expose data in the URL and are subject to length restrictions. If you use the GET method in Retable's webhooks, the 'Body' field will be inactive.

POST: The most frequently used method in webhooks is POST. When a webhook event is triggered, the sender (publisher) sends an HTTP POST request to the listener's URL endpoint. The POST request typically carries data related to the event in its payload. The listener's server processes this data and performs the necessary actions based on the event.

DELETE: The DELETE method is used to request the removal of a resource at the specified URL. While not commonly used in webhooks, it could be employed to trigger actions that remove data or resources based on a specific event.

UPDATE: The UPDATE method is used to update or create a resource at a specific URL. It is often used to update an existing resource or create a new one if it doesn't already exist. The UPDATE could potentially be used in some scenarios where the event data needs to update an existing resource on the listener's side.

When designing a webhook system, it's essential to choose the appropriate HTTP method based on the nature of the event and the action required on the listener's side. Typically, POST is the preferred method for webhooks since it allows for the transmission of event-specific data and actions.

Params

"Params" is a shortened term for "parameters." Parameters, often referred to as "query parameters," are key-value pairs of data that are included in the URL of an HTTP request. These parameters provide additional information to the server about the request being made. Webhooks may use parameters to communicate specific details about an event or to customize the behavior of the webhook request.

Query parameters are typically added to the URL after a question mark (?) and are separated by ampersands (&). Each parameter consists of a key and a corresponding value, like this:

https://example.com/webhook?param1=value1&param2=value2

‍

For example, in a scenario where we use Zapier's webhook trigger, the parameters we add to the Retable webhooks will look like the image below.

Here's an example of how parameters might be used in a webhook context:

Suppose you have a webhook that sends information about a new user registration event to a listener. The URL endpoint for the listener could include query parameters that provide additional context about the event:

https://listener.example.com/webhook-endpoint?event=user_registration&username=johndoe&email=john@example.com

In this example:

• event is a query parameter indicating the type of event.
• username is a query parameter containing the username of the newly registered user.
• email is a query parameter containing the email address of the newly registered user.

The listener's server can then parse these query parameters to understand the specifics of the event and the associated data.

Keep in mind that while query parameters are a common way to pass data to webhooks, they are included in the URL, which means they might be visible in logs, analytics, and potentially be cached by intermediaries. Depending on the sensitivity of the data being transmitted, query parameters might not be suitable. In such cases, it's advisable to use other methods, such as sending data in the request body using the POST method, which offers more privacy and security.

Headers

Headers refer to the metadata included in the request or response that provides additional information about the communication between the client (sender) and the server (receiver). Headers convey various details about the data being exchanged, the nature of the request or response, and instructions for how the communication should be handled.

In Retable webhooks, the header section contains two values; Header Name and Header Value. The Header Name is "User-Agent" by default and Header Value is "Retable" by default. If you want, you can add new header values.

Headers are an important part of webhooks, especially when it comes to security, authentication, and conveying relevant details about the event or request. Properly configuring and utilizing headers can enhance the reliability and security of webhook communications.

Body

The "body" refers to the main content of the request that is sent from the client (sender) to the server (receiver). The body of an HTTP request typically carries the payload or data associated with the request. This payload can be in various formats such as JSON, XML, plain text, HTML, or other types depending on the nature of the communication. In Retable's webhooks, payloads are currently only in JSON format.

When a webhook is triggered, the data related to the event is often included in the body of the HTTP request. The body contains the information that the listener (subscriber) needs to process and act upon in response to the event.

For example, let's say you have a webhook that sends notifications whenever a new user submits your Retable form. The body of the webhook request might contain a JSON payload like this:

{
 "event": "form_submission",
 "user": {
   "id": "12345",
   "name": "John Doe",
   "email": "john@example.com"
 }
}

In this example:

• The event field indicates the type of event, which is a user registration event.
• The user field contains the details of the registered user, including their ID, name, and email address.

The listener's server would parse the JSON data from the body of the request and take appropriate actions based on the event and user information provided.

It's important to note that the body of an HTTP request is particularly relevant when using the POST method, as it's commonly used to transmit data from the client to the server. The body allows for more complex and structured data to be included compared to other parts of the request such as headers or query parameters.

In Retable webhooks, you can leave the body blank if you want. If you select "none" for the body field, your webhook's body will be empty. If you select the "application/json" option, you can select which columns you want to include information about in the body section.

Since we have activated 2 columns on this example, the body of this webhook will be as follows:

PS: If you enable more columns in the body section, data on those columns will be added to your body.

How to Create a Webhook Call

You can access Webhooks from Retable's automations section of your Retable projects.

Before creating your webhooks, you can check out this video to see how Retable's automation works. Thus, by understanding the basics of automation, you can create your webhooks more easily.

To start the call webhook action, you must first select a trigger from the automation section. This trigger determines which action will trigger your call webhook action. Call webhooks action cannot be used with the “at a scheduled time” trigger.

You can use one of these triggers to use "Call Webhooks action"

• When row added: When building an Automation, you may choose a trigger to start that automation. The "When row added" trigger allows you to trigger (or run) an automation for each record that enters a selected view (after the automation has been turned on).
• When row deleted: When building an Automation, you may choose a trigger to start that automation. The "When row deleted" trigger allows you to trigger (or run) an automation for each record that enters a selected delete (after the automation has been turned on).
• When cell updated: When building an Automation, you may choose a trigger that will start the automation. The "When cell updated" trigger allows you to select an entire record, or individual fields in a record, to monitor for updates. Anytime the select fields are updated the automation will trigger (or run) and start the action you created.
• When form submitted: When building an Automation, you may choose a trigger that will start the automation. The "When form submitted" trigger track every record that comes into the table. An e-mail is sent to the relevant people each time a form is submitted.

If you choose "When row added", "When row deleted" or "When form submitted" trigger types, you need to select the table as well. If you choose the "When cell updated" trigger type, you need to select a table and a column.

After making all your trigger settings, you can contunie to select the "Call webhooks" action from the "Action type" section.

‍

You can now set up your webhook in accordance with the instructions in the "Fundamentals of Retable's Webhooks" section above!

The steps simply should be as follows;

• HTTP Method& URL: You can choose a method from the list in the HTTP method field and enter a URL in the URL field. The web address to which the HTTP request will be made must be entered in the URL field.
• Params: Then, you can switch and edit the Params  tabs. The parameters in the URL will automatically added to the Parameters list. Also, every parameter you add to the parameters list will be added to end of the URL.
• Headers: You can send the value of the triggered column by typing the name of this column in the Header field with curly braces. If you do not add anything to the Headers field, the headers information assigned by Retable by default will be used.
• Body: You must select POST, DELETE or UPDATE as the HTTP method to access the body field. This field forms the body of your HTTP request. If the Content Type field is "none" in this field, the body will not be sent in the request. ‍
• Save and Activate: After you finish your webhook settings, you can save and activate the automation.