API DocsCommunityAPI Playground

## What is a trigger?

A trigger is a type of workflow block that invokes an automation. Typically the trigger will happen (for example, a status changes to "Done") and this will trigger one or more action blocks.

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.).

## Custom triggers

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 for monday-to-monday automations. If there's a specific trigger you need that isn't available in our Built-in Triggers, they can still 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.

When building a custom trigger, you'll need to define a few things that make up the API of your trigger:

  • Input fields, which are the configuration your trigger needs to run

  • Output fields, which is the data your trigger will pass to the action

  • A subscribe URL

  • A mechanism to store webhook URLs and call them when the specific trigger is invoked

  • An unsubscribe URL

## Build your first custom trigger

To start building a custom trigger, you will need to open the "Workflow Blocks" tab of your app's integration and click "Create New" and then on "Trigger"

1786


### 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 are how you pass data between your custom trigger and the action. You can map your trigger's output fields to the input fields of your action, thus combining them and allowing for more logic.

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

The subscribe/unsubscribe endpoints are called by the monday.com platform whenever a specific user adds or removes recipes from a board.

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.

When the monday server calls these endpoints, it will supply the current configuration for any input fields (for example, the board ID).

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**:


**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:

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:

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 webhookURL 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**:

## 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**:

**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 a user disables the recipe the Unsubscribe Url will not be called. In this case all the calls to the action from this specific trigger will be ignored.
## Congratulations Builder!
Once you've finished this article, read these to learn more about key concepts:
  • [Custom Actions](🔗) 
  • [Quickstart Guide: Integration Recipes](🔗) 
  • [Authorization for Integration Recipes](🔗) 
  • [OAuth and Permissions](🔗) 
  • [Frequently Asked Questions](🔗)
  • [Developers community] \(<https://community.monday.com/c/developers/8>)
Join our developer community!
We've created a <a href="https://community.monday.com/c/developers/8" target="_blank"> community</a> specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎