Webhooks rely on subscribing to an event, essentially you can think of them as callbacks which listen for an event and send data to a provided URL when the event happens.
If the API that you are working with supports setting up a webhook, you can set your Connector to automatically install webhooks via API Calls. This requires you to set up three new methods:
- Create Webhook method that will create the webhook in the external site,
- Delete Webhook method that deletes the webhook,
- Parent Webhook method that will function as the “shell” which calls the other two methods.
The Create Method will be called when the webhook first runs, and the Delete method will run when the webhook step is deleted from the Connector.
The Create Webhook method will be a POST request which is called the first time the cycle containing the webhook is executed. Each event that you want to create a webhook for will need to have a their own Create method.
The Delete Webhook method will be a generic method which you can assign to all webhooks for the same API.
Setting up webhooks in Cyclr
Webhooks are created within Cyclr by having a Parent Webhook method with two hidden methods, a Create Webhook method and a Delete Webhook method, that are assigned to the Parent.
As you will need to create three new methods for your Webhook, let’s navigate to your Connector’s Method tab. First, create a category called Webhooks. This is where you will add all of your webhook methods to keep them neatly together.
Next, you will need to create your ‘Create’ and ‘Delete’ Webhook methods, before adding your ‘Parent’ Webhook method.
Step 1: Creating the ‘Create Webhook’ Method
Let’s start creating our Create Webhook method by clicking on the ‘Add New Method’ button. As mentioned earlier, your Create Webhook method will be a POST request, so go ahead and set your Method type to ‘Action’, and your HTTP Method as ‘Post’.
As both the create and delete methods should not be accessed by end-users, they need to be set as Hidden. You can do this from the method’s settings, by setting the ‘Hide?’ option to True.
Like with any other POST methods, you will need to specify the Request Format and Response Format for your Create Webhook method.
In the Request format of the Create Webhook method, you should include the following fields:
| Connector Field | System Field | Display Name | Hidden | Default Value | Notes |
|---|---|---|---|---|---|
name | WebhookName | Webhook Name | true | Create Webhook | The name of the event which we are subscribing to. |
url | CallbackUrl | Callback URL | true | {{Cyclr_Webhook_Url}} | This field is automatically generated by Cyclr with the URL of the webhook that is initiated. This is so the 3rd Party API knows where to send the data. |
[event] | Event | Event | true | webhook_created | The event which we are subscribing to. |
TOP TIP! The field containing the {{Cyclr_Webhook_Url}} value should always be set to hidden. This field is then automatically populated with the URL of the webhook in which the method is initiated.
In the Response format of your Create Webhook method, you will need to map the id field to a special system field: Cyclr_Webhook_Id. This will save the ID as a MergeField parameter, so that you can access it later in the delete method.
| Connector Field | SystemField | Display Name | Notes |
|---|---|---|---|
| id | Cyclr_Webhook_Id | Cyclr_Webhook_Id | This System field saves the ID as a parameter merge field called Cyclr_Webhook_Id, so that we are able to delete it at a later time. |
For example if the response from your POST is:
{"id": 1, "active": true}
Then you would setup your field mappings like this:
Step 2: Creating the ‘Delete Webhook’ Method
Unlike Common REST API Cycles, webhooks are continuous. They will run until the user stops the cycle. This is the point where the delete webhook method will trigger. The delete method is called when the user removes the webhook step from a cycle.
Your Delete Webhook method will need to be ‘Action’ method type, with an HTTP method set as ‘Delete’. However, you should add {{Cyclr_Webhook_Id}} MergeField at the end of your endpoint.
Using the merge field {{Cyclr_Webhook_Id}} will pull in the webhook ID that was saved from the Create call and populate the URL with the correct Webhook ID. So your Delete Webhook method endpoint will look like something like this:
https://webhookexample.com/api/v1/webhooks/{{Cyclr_Webhook_Id}}
Remember to set your Delete Webhook method as Hidden.
In the Parameters tab you must also create Cyclr_Webhook_Id MergeField parameter, which should always be set to hidden:
Step 3: Creating the ‘Parent Webhook’ Method
Now that we have both our Create and Delete Webhook methods set up, we can start creating the ‘Parent’ webhook. This the Webhook method that your end user will interact with.
The Parent webhook method triggers Create Webhook method the first time the cycle is executed. This method will also trigger the Delete Webhook method when the webhook step is deleted from the Cycle.
First, go ahead and start creating a new method from the ‘Add Method’ button. When creating your webhook method, the method name should match the event which you’re triggering, e.g. Contact Created Webhook.
Next, set the Method Type to ‘Webhook’. This will open new fields, where you can map your Create Webhook and Delete Webhook Methods:
These are drop-down menus, so you may need to scroll to find your Create and Delete Webhook methods from the list, depending on how many methods you have already created.
Remember to click on Save at the bottom of the page to save your progress.
When creating the field mappings for your Parent webhook method, the only ones to populate should be Request Format. In here you should generate mappings for the data that will be posted to the webhook.
The request format of your parent webhook method should match the event which you would like to subscribe to. For example, the Contact Created Webhook would have a request format that matches that of a Create Contact method.