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. You can set multiple conditions for receiving events for each endpoint in the set.
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 an additional field 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 latter 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 key Value: This is where you can specify your conditions for which you want your trigger to run. As we will receive multiple events on a single URL, using this Lookup Key we will determine the event type that took place and its specific value for which we need the corresponding trigger to run. The name of the event or attribute goes in the left field e.g. "subscription type" or "List ID". The actual value of the event is to be provided in the field on the right side i.e. contact created, contact updated, etc.
- Add/remove a condition: You can add multiple conditions and specify additional event types and their values according to your requirements for which you want your trigger to run. Clicking the ( + ) button will add another set of fields for a Key and Value. The ( - ) is there to remove any condition that you want. If there are no extra conditions, this button just clears the values that you have provided in the fields and makes them blank.
Adding extra conditions will look like this:
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 JSON Key and Value condition field
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 Field name and the contact.creation as the Value. This means a new contact is created. 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.
Setting this condition in our common endpoint will look like this:
You can now add more conditions for the endpoint if you require. Just click the Add ( + ) button on the right.
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.