A number of apps implement events batching and send multiple events of the same or different types in a single webhook request payload. To support such apps, we provide a feature called “Endpoints Sets”. An Endpoints Set is a collection of incoming endpoints where one of them is the parent and all other endpoints are its children. The external app sends batches of events to the parent endpoint’s URL, which then delegates each individual event to its respective child endpoint.
Let’s walk through an example and make the concept clearer.
Creating an Endpoint and assigning a Set Name to it
Let’s say we want to create a Trigger, “Contact Created” in your app, HubSpot. Head over to the Triggers tab, and click the Create Trigger button. The scope of this article is to walk you through the process of creating trigger endpoints for apps that send multiple events in a single webhook request. Learn about Trigger Basic Info, Authorization and Adding Activity fields to your Trigger, here.
Once the trigger basic info, authorization, and activity fields are in place, we will now move forward to creating the trigger endpoint. Since this is a webhook based trigger, we will keep the toggle for Is Poll Based?, OFF! From the Endpoint field drop-down menu, select the Create a New Endpoint option. The endpoint creation form will appear. Since this is a trigger endpoint i.e. we will be receiving a webhook from an external app so the endpoint type should be set to Incoming. Learn more about endpoints, here.
The Request URL will be generated automatically once the endpoint is saved. Below the Request URL, you can view a Toggle, Make this a common endpoint, as shown below.
If you turn on the toggle, it will make this endpoint a common endpoint which means it will become part of an Endpoints Set.
Once you turn the toggle button on, you can view some additional fields for this endpoint, like shown below.
Here are the details of these fields.
- Webhook Set Name: When you make an endpoint a common endpoint, it becomes part of a set. You can either select an existing set or give a new name. In the later case, a new parent endpoint will be generated automatically when this endpoint is saved and both of these will become part of a new common set.
- JSON Lookup Key: As we will receive multiple events on a single URL, using this Lookup Key we will determine the event type that took place and run the corresponding trigger.
- JSON Lookup Value: This field will take in the actual value of the event i.e. contact created, contact updated, etc.
Let’s see how these fields work for the running example.
First of all, you need to enter a Webhook Set Name, let’s say we name it Webhook Receivers. When you will save this endpoint, it will be created within the set Webhook Receivers.
Setting up the Values of JSON Lookup Field and Lookup Value
The HubSpot Payload
From the HubSpot documentation, we know that the webhook payload looks like this (the code below has been formatted for better understanding):
From the payload structure above, we can see there is an array with two objects in it. Each object contains a property, “subscriptionType”, which has a different value for each event type.
For this particular example, we will enter subscriptionType as the JSON Lookup Field and the contact.creation as the Lookup Value. So, whenever we receive a batch of events on parent endpoint’s URL, this particular endpoint and its associated trigger will execute only for those events which have subscriptionType=contact.creation.
Our common endpoint fields will finally look like this:
If you also want to handle those events that have subscriptionType =contact.propertyChange , then you should create a new Trigger with a new endpoint. Turn that endpoint into a common one too, add it to the same set, specify same JSON Lookup Field but provide contact.propertyChange as the JSON Lookup Value. That trigger will start receiving events matching this criterion from the same parent endpoint.
The Parent Endpoint
When you create the common endpoint, a separate parent endpoint for that set is created automatically along with your endpoint. All the endpoints in that set are its children. So, when the time comes to provide a URL to HubSpot where it will send the webhooks, we should provide the URL of the parent endpoint for that set. HubSpot will send webhooks to parent endpoint URL, and all the children endpoints of that parent will check whether the event they are looking for has occurred or not. If yes, the respective trigger for that endpoint will be executed.
The parent endpoint will belong to the same “Webhook Receivers” set, as the image below shows.
Response template of a parent endpoint should fulfill the following criteria:
- Its output should be a JSON array
- The objects of the array should have the key-value pairs that we provided as JSON Lookup Key and Lookup Value in the children endpoints, directly
The default Response Template of the parent endpoint that is generated automatically just passes through the incoming webhook request body as is, assuming that it is already in the correct format. But if you want to make any changes to it, for example, if the array of events is not at the top level but inside a property then you can manipulate it in the Response Template field using Twig syntax and generate the required output.
Learn how to set up auto hooks for triggers.