Triggers are events that start an integration. This reference guide describes the API that your app will use to start integrations.

Background

Trigger blocks control when an integration is run. Many apps run their triggers based on webhooks from a third-party system but you can use any event.

There are three steps that your app must handle:

1. User adds your trigger to a board: monday calls your subscribe URL
2. Your app trigger the subscription: You call the subscription's webhook URL
3. User deletes your trigger: monday calls your unsubscribe URL

To learn how to configure your block in the monday UI, read the "Build a trigger block" guide.

Reference

Subscribe URL

monday will send a POST request to the Subscribe URL a user creates an integration with your trigger. The request will contain a webhook URL. When your app calls this URL, monday will run the subsequent actions in the integration.

Method: POST

Body

{
  "payload": {
    "webhookUrl": "https://api-gw.monday.com/automations/apps-events/481690204",
    "subscriptionId": 481690204,
    "blockMetadata": {
      "shouldCalculateDynamicMapping": false
    },
    "inboundFieldValues": {
      "text": "hello world"
    },
    "credentialsValues": {},
    "inputFields": {
      "text": "hello world"
    },
    "recipeId": 30440657,
    "integrationId": 398739197
  }
}

Authorization header

The request will contain an authorization JWT in the headers.

Webhook URL

The payload contains a webhook URL, which your app can call to invoke the trigger. The next section shows how to use it.

Response

Your endpoint should respond with a 200 status. You should store the subscription details in your app's storage so you can trigger it later.

If you want to use a different ID for the subscription than our subscription ID, you can pass a webhook ID at this step. Otherwise the subscriptionId will be used.

{
  "webhookId": 111
}

Triggering your block

When you want to invoke the trigger (e.g. when a lead is created in the customer's CRM), you need to identify which subscription you would like triggered on the monday.com side.

Once you identify the correct subscription, send a POST request to the corresponding webhookURL:

Method: POST

Authorization: JWT signed with your app's signing secret

Body

{
  "trigger": {
    "outputFields": { 
      "text": "Hello?", // replace with your block's output fields
      "number": 9
    }
  }
}

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": 481690204 //the webhookId supplied by your Subscribe endpoint, or the subscriptionId
  }
}

Authorization header

The request will contain an Authorization JWT in the headers.

Response

After the call, you should respond to the endpoint with 200 HTTP status without the payload. If you respond with an error, not 2XX status, we will prevent the user from deleting the recipe.

You should also remove the subscription from your persistent storage based on the webhookId provided.

📘

When is the unsubscribe URL called?

The Unsubscribe URL is only called when the recipe is deleted, not when it is turned off. In this case all the calls to the action from this specific trigger will be ignored.

Glossary

Events

Subscribe event: What happens when a user adds your trigger to a monday workflow. monday will send a webhook to your subscribe URL.

Unsubscribe event: Happens when a user deletes or turns off your trigger. monday will send a webhook to your unsubscribe URL.

Invocation: The process of triggering a trigger block. Your app will send monday a webhook.

Input fields: Data the trigger needs to run, typically defined by the user when they create the integration.

Output fields: Data emitted by the trigger, typically data and metadata about the event.

Data flow diagram

The following diagram describes a custom trigger that relies on a webhook from an external CRM.