Your actions and triggers can have a requirement to perform certain API operations at different points in the lifecycle of an integration. For example:
- You need to fetch some properties via an API call and store them as activity fields values when integration is created.
- If you are creating a trigger, you will need to create a webhook subscription when a new integration with that trigger is created, and delete the subscription when that integration is deleted.
- You might need to create a “Bot User” for the integration in your app via API. All content generated by the integration will be posted on behalf of that bot user. When integration is deleted, you will probably need to delete or suspend that bot user too.
You can define an endpoint to specify details of the API calls that need to be performed and assign those endpoints to hooks here. In this way, whenever an integration involving your action or trigger is created, your endpoints will be executed on the respective life cycle points.
We support six types of hooks which are as follows which can be executed at any stage of the integration life cycle, depending upon the requirement. In most of the cases, the hooks are used before we save an integration and after we delete an integration. We will discuss a few cases in detail below. Before we move forward there are a few things to keep in mind while we are dealing with hooks.
- If the name of the top-level variable and machine of the activity field are the same, the value can directly be stored in that activity field in the context of hooks.
- Some system variables are available directly in the context of hooks, they are discussed below.
A few hooks are explained with examples in this article.
An endpoint to be executed before a new integration is created. If this endpoint returns an error response, integration will not be created. Most of the time in this case we are creating a Webhook, for a particular event in another app. For more details about Webhooks, click here. We will take an example for better understanding.
Suppose we are creating a trigger To-do Created in Basecamp. How will Basecamp know when to notify us about the event? So, before we save our integration we create a webhook, send it to Basecamp and subscribe to that particular event. Basecamp will then know always to notify us when the subscribed event takes place. We will configure the endpoint that will send us webhooks whenever the subscribed event takes place.
From the Create a Webhook Docs, we know the following endpoint creates a webhook in Basecamp
where 1 is the project ID.
To receive a webhook we will need to provide the Basecamp account and a project we will link to it. We need to append the Account and Project IDs in our URL. If a to-do is created in this account, notify us.
The values of the activity fields that we will use in this endpoint URL will be the account and project fields. The machine names of these fields are basecamp_account and basecamp_project. These field values can be read for the current integration off of Twig requestBody object in the endpoint URL. So, Our URL will look like this:
As specified in the docs, the JSON request should include the following
"types": [ "Todo", "Todolist" ]
The payload URL specifies the URL that Basecamp will call whereas the type tells the event type we are subscribing to. Keeping the above JSON snippet in mind our request template will look like as shown below
"types": [ "Todo" ]
Two system variables have been used in the code above; endpoint and integration_id. The requestBody.endpoint carries the URL that will be called by Basecamp and requestBody.integration_id carries the value of the integration against which the webhook is being created. So now when Basecamp hits our URL we know which integration to run. The type Todo has been specified as we are working in the Todo created.
When we are dealing with webhooks, we will create an additional hidden Webhook ID field, which will save the ID of that particular webhook. We will extract the webhook ID from the response received and will return it as a top level property of the JSON object in our response template with the same name as the machine name of activity field in which we want to store it. Then integry will automatically store this value in that activity field for each integration, and it will be available to other hook endpoints of same activity for respective integrations.
Assuming that the machine name of the field is basecamp_webhook_id, our response template will look like this.
An endpoint to be executed after a new integration is saved. The actual webhooks we receive when the subscribed event takes place.
A user can update an existing integration. The endpoint that executes before an updated integration is saved is configured in the pre-update hook. Suppose a user connected your app to GitHub. The repository he configured when he created the integration at first was repo1 in his GitHub account, later he wanted to change the repository. So he selects a new repository from the dropdown list. At the time this endpoint is called and the new integration details are communicated.
An endpoint to be executed after an existing integration is updated. Once the integration is updated, a different endpoint will be called in case of the subscribed event.
An endpoint to be executed before an integration is deleted.
Post delete hook
An endpoint to be executed after an integration is deleted. Suppose a user deletes an integration, we need to destroy the corresponding webhook too. Otherwise, we will keep on receiving webhooks of events that we no longer need.
In this case, we delete webhook we created at the start. Taking the running example, To-do Created in Basecamp we will see how this works.
From the API Docs we know the following endpoint deletes a webhook
where 1 is the project ID and 3 is the webhook ID. The values of the activity fields that we will use in this endpoint URL will be the account, project, and webhook IDs. The machine names of these fields are basecamp_account, basecamp_project and basecamp_webhook_id respectively. These field values can be read for the current integration off of Twig requestBody object in the endpoint URL. So, Our URL will look like this:
The URL specifies the path and identifies which webhook to delete. These values come from the activity fields.
The Request Template is not supported by the DELETE HTTP verb, hence it does not appear. We will leave the Response template empty as we do not need to further process the response received. The story of this webhook ends here.
The case discussed above was for Basecamp, these templates and syntax may differ vary from case to case.