Build Integration Recipes

Custom Triggers

Build a custom trigger that will listen to events on external system to ignite the integration recipe

Build Custom triggers

The monday Apps framework supports two types of triggers: built-in triggers and custom triggers.

Built-in triggers are used when you want your recipe to be triggered by an event on the monday.com platform (e.g creating an item, updating a column, etc.). These can be used as default triggers in your recipe.

Next are custom triggers. You can use custom triggers when you want your recipe to be triggered by an event on your system side to perform some action on the monday.com side (e.g. a lead in a CRM system was created, the inventory in an ERP system was updated, etc.).

In order to successfully use custom triggers, you will need to build the custom trigger and connect it to the system you are using.

Custom triggers can also be used to perform specific prompts in the monday.com system. These triggers are not provided in the pre-built list of monday.com triggers, but can be implemented on the backend with the help of monday webhooks or data polling.

Now that we identified the 2 different types of triggers, let's get to building them.

To start building a custom trigger, you will need to open the "Triggers" section of the integration feature found in your monday app and click "Create New Trigger."

Input fields

You can define the input fields for your custom trigger; in the event you want to choose some parameter in the recipe.

For example, a user can choose a "Leads Category" if they are looking to select leads from a CRM system. This will then sync into monday.com.

For this specific case, you would be creating a custom field type with the ability to gather leads from categories on the backend. This would then use these as an input field for your custom trigger.

Output fields

Output fields will become the API between your custom trigger and the action. This provides you with the option of mapping these as input fields, thus combining them with your custom trigger.

Note : The max character limit for a custom trigger or action is 255 characters for each one - meaning they can be used together for a total of 510 characters on the entire recipe. As a best practice we recommend making recipes short and easily configurable, breaking the logic into multiple recipes if necessary.

Subscription URLs

Endpoints are called by the monday.com platform whenever a specific user adds or removes recipes from a board. When this happens, context of. the recipe will be provided.

The endpoints of your server are represented by two types of URL's: a Subscribe URL and an Unsubscribed URL. These endpoints will both need to be defined before they are called by the monday.com platform.

These will need to be implemented by your server in order to save/remove context information as well as for understanding which data needs to be updated when the custom trigger is called.

The full flow looks like this (e.g for the case of custom trigger "When the Lead in CRM system was created"):


Subscribing to your trigger

Subscribe URL

Each time a user adds your recipe to a board, your Subscribe URL will be called with the following parameters:

Method: POST

Body:

{
  "payload": {
    "subscriptionId": 123, //unique identifier of the specific user subscription    
    "inputFields": { ///values of all input fields, which were configured for your custom trigger
      "boardId": 118607425 //f.e. boardId
    }, 
    "webhookUrl": "https://api.monday.com/trigger/123", //callback url, which you should call when recipe action should be triggered
    "recipeId": 123456 // unique ID of the recipe in your app. the same same recipe ID will be sent if two different accounts are using the same recipe. 
}

Authorization header

Whenever the Subscribe URL is called, the authorization header will be included. The authorization header is the JWT token that is signed by the Signing secret of your app.

The JWT token should be verified on each call with your Signing secret.

This JWT token has the following structure:

{
  "accountId": 739628, //user account id
  "userId": 4616666, //user id
  "aud": "https://my-app-backend.com/subscribe", //which URL was meant to be called
  "exp": 1592342588, //when the token will be expired
  "iat": 1592342288 //when the token was issued
}

Always make sure to verify that the token is not expired and that the URL in the "aud" field is your endpoint. This is to prevent your token from being stolen and used.

Response

During the response call, you will have the opportunity to manage your subscription and place it in your storage.

While this is happening, your endpoint must respond to the response call in a JSON format with a 200 status and the following response body:

{
  "webhookId": 111
}

In this instance, webhookid is the unique identifier of a created subscription instance on your side. This webhookid, which can be in any format, will be sent to your Unsubscribe URL when the user deletes the recipe.

If you do not respond with the webhookid, the subscriptionid will be used instead.

Calling your action

Whenever custom events are triggered in your system (e.g. when a lead is created in the CRM) you will need to identify what instance of the recipe (subscription) you would like triggered on the monday.com side.

A POST request to the SubscriptionURL should then be sent, the one which was sent to your SubscriptionURL, with the set of output fields defined in your custom trigger.

Your request should also include the app's Signing Secret in the Authorization header.

Body:

{
  "trigger": {
    "outputFields": { ///values of all output fields, which were configured for your custom trigger
      "itemId": 256478769 //f.e. itemId
    }
  }
}

Unsubscribing from your trigger

Unsubscribe URL

When a user removes your recipe from a board, your Unsubscribe URL will be called with the following parameters:

Method: POST Body:

{
  "payload": {
    "webhookId": 111 //the same webhookId, which you responded in your Subscribe endpoint
  }
}

Authorization header

Every call to Unsubscribe Url will include an authorization header, which is JWT token signed by the Signing secret of your app. You should verify it on each call with your Signing secret. JWT token has the same structure as for Subscribe Url.

Response

During this call you should remove the subscription from your persistent storage based on the unique webhookId. After it, you should respond to the endpoint with 200 HTTP Status without the payload.

If you will respond with an error (not 2XX status), we will prevent the user from deleting the recipe.

Note:
If user disables the recipe - Unsubscribe Url will not be called. In this case all the calls to action from this specific trigger will be ignored.