Create Webhook Based Trigger Endpoint

A detailed guide on how to create action endpoints

Written by Sitwat Atiq Updated over a week ago

Triggers are a very important part of an integration. It is an event that starts from your app as To-do item created, New Contact added and more depending upon your app. When these events occur, we need to know about them so that the corresponding integration could be run. We subscribe to the particular event’s endpoint, and in case of the event occurrence, we receive Webhooks. The purpose of this article is to guide you through the whole process of creating a trigger endpoint using Integry. These endpoints are created either under the Endpoints tab in your app or when you create a trigger, you select Create a new endpoint option in the Endpoint field.

How to create a Trigger Endpoint?

Let us walk through an example of how to create a trigger endpoint. Since this is the webhook based trigger, so we will set the Is Poll Based? toggle button off as shown below.

When you select the Create a new endpoint option from Define the Trigger endpoint drop-down menu as shown below, you need to fill the endpoint creation form.

The basics of this procedure can be learned here. We want to create a trigger To-do Created in Basecamp. We will enter the name of the endpoint and select Incoming endpoint type (as we will receive the request from Basecamp when the event occurs).

Request URL

This is the trigger endpoint URL which will receive a request from the third party app. The URL is generated, automatically in case of Incoming endpoint type. The HTTP Verb ANY is already selected for Incoming type. It is configured with your app at the time of integration creation. You can view the URL when you want to edit the endpoint in the Endpoints tab in the Apps menu.

Response Template

Response templates play a very important role in trigger endpoints. When we receive a Webhook from another app, we need to translate the request received in a format that can be understood by us. Response templates are used for this purpose. It takes JSON object as input, for composing our template we use Twig templating language.

In case of Basecamp, when we receive a webhook it contains a list of all event types. The payload and the structure of the webhook received is specified in an app’s API documentation.

Since the payload is very large, we will talk about the few payload properties that we require to transform our request. We need to find if the event the user subscribed to took place or not. Using the requestBody variable we will access the data received in the webhook. requestBody is a top-level variable that contains the payload of the incoming request.

If you read the request payload structure, we can see we need two properties to get our information. The kind variable at the start of the payload tells us the nature of the event. As we are subscribing to To-Created event, there can be other event kinds like to-do copied, to-do completed etc. The recordings key contains the details of the events that took place in a form of an array. How will we find the event type, see the code below:

{% if requestBody.kind == "todo_created" %} (1)

{{ requestBody.recording | json_encode | raw }} (2)

{% endif %}

So what exactly is happening?

We have implemented a conditional statement to check whether the payload has what we were looking for. The conditional statement fulfills two purposes here. One is to find if the list of the events contain the name of the event the user subscribed to. If yes, we encode the recording object in the request body received. This makes sure which integration has to be executed and the encoded JSON object is passed to action activity field of that template. In case we do not find the event in the request, the request received stays as received. No integration runs.

The data received is being encoded. The json_encode filter generates a JSON object as output for further processing.

In some cases you can filter the request without any conditional statements, again that depends upon how the other app has implemented their webhooks.

Tracking Property Name

This field takes in the object property name that uniquely identifies the object. Some good candidates could be "id" of objects or the last_updated_timestamp.

Integration Mapping

When integrations execute, communication takes place through endpoints. There are apps that support per user, per event multiple subscriptions and webhooks whereas there are apps that only support one endpoint for all users and events. Let us see how do we manage both scenarios.

Extract directly from Request

Considering the To-do Created example, at the time of integration creation, Integry configured an endpoint with the user Basecamp account. This endpoint is where Basecamp will send a request in the future. The structure of the endpoint is shown below

When a to-do item is added, we will receive a webhook from Basecamp on the endpoint with ID 31118. So now we know, a to-do item was added but how do we know which integration to execute! For this, we will extract the integration ID from URL and run the respective integration. Integration IDs are generated automatically at the time of integration creation for every integration. It differentiates integrations, even for the same user.Basecamp supports different endpoints per user or per event as we can see here.

When we select the HTTP Request, we will provide the Integration ID in the form of a variable as shown above. We have defined a query variable that extracts the query parameters from the URL (in this context). The value of a particular query parameter can be accessed as shown in the figure above. To retrieve integration ID from the URL, you must enter query.integration_id in the Integration ID field.

Determine based on Activity Field Value

There are apps that do not support multiple endpoints per user or per event. In this case, we provide them with a single endpoint where we receive an incoming request (webhook) whenever an event occurs.

To delve deeper into this, let us consider an example. Suppose we created a trigger Contact Created in HubSpot. As we go through HubSpot documentation, we learn that HubSpot requires one endpoint where all of the communication takes place. We configure the endpoint with the HubSpot app in Integry. In future, HubSpot sends all events on it for all users who have authenticated their HubSpot accounts using our app. The endpoint looks like this

When an event will occur we will receive a webhook on this endpoint. But how do we determine which integration to execute? We will look for a property that remains unique for every event or user. Studying HubSpot Webhook payload, we know it consists of multiple data attributes. The one we will use to find our integration is the PortalID (in this case only, each app has it’s own unique object/variable)

[ { ….

portalID: 444,

…. }]

In our database, we map portalID and integrations created across that ID. So, when we receive the webhook we extract the portalID and pass it to a database where we retrieve all integrations saved against portalID. A list of integrations is returned and we run them all.

The Field takes the machine name of the activity field that saves the portal ID. This field will be hidden because the user has nothing to do with it. This is just to store the value of Portal ID to run through our database.

The Lookup Value Field takes the value of portal ID extracted from the body of the incoming request. We have defined a top-level array requestBody that stores the value of the incoming request. The request received by HubSpot is in the form of a JSON array. We can read data off it by using requestBody[] in combination with the name of the property like requestBody[0].portalID. The double curly braces output the value of the variable. This is the Twig templating language syntax.

These examples above are Basecamp and HubSpot specific, these templates vary from app to app.