If your application needs real-time updates from monday.com boards, you can use our webhooks integration.

Intro to monday.com Webhooks

What is a webhook?

Webhook (also called a web callback or HTTP push API) is a way to provide real-time information and updates. A Webhook delivers data to other applications as it happens, meaning you get data immediately. This makes Webhooks much more efficient for both providers and consumers.

The monday.com webhook integration allows you to subscribe to events on your boards, and get notified by an HTTP post request to a specified URL with the event information as a payload.

When would I use a webhook?

Instead of constantly polling the API for updates, you can use a webhook to notify your URL when a certain event has taken place on your boards.

How do I add a webhook to a board?

To add a webhook to one of your boards, click into any one of your board's Integrations Center. Look for our Webhooks app and select the webhook recipe of your choosing. Lastly, provide the URL that will receive the event payload. Our servers will send a "challenge' to that URL to verify that you control this endpoint.

How to verify a webhook URL?

The URL you specified should be, of course, controlled by your app. Our platform checks this by sending a JSON challenge to your endpoint, and your app should respond back with the same challenge.

We will send a JSON POST body, containing a "challenge" field. This is a randomly generated token that we expect you to return as a "challenge" field of your response JSON body to that request.

Here is how the "Challenge" will look like:

{
 "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"
}

The response body should be an identical JSON POST body:

{
 "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"
}

Here's a simple example of a webhook listener that will print the output of the webhook and respond correctly to the challenge:

app.post("/", function(req, res) {  console.log(JSON.stringify(req.body, 0, 2));    res.status(200).send(req.body);})

You're now ready to start using a webhook!

Learn more

To learn more about creating webhooks through monday.com, check out our comprehensive guide here.

Webhooks Mutations

Required scope: webhooks:write

Create a Webhook

The mutation allows you to create a new webhook. After the mutation runs, a webhook subscription will be created based on a specific event. Every time the event happens on your board, the webhook will send data about the event to the subscribed URL.

The URL will have to pass a verification test, where we will send a JSON POST body request containing a challenge field. We expect your provided URL to return the token as a challenge field in your response JSON body to that request.

The webhooks that you can subscribe to via the API include:

  • When a new update is posted - create_update
  • When any column changes - change_column_value
  • When an item is created - create_item
  • When an item's name changes - change_name
  • When a column changes - change_specific_column_value
  • When a sub-item is created - create_subitem;
  • When any sub-item column changes - change_subitem_column_value;
  • When a sub-item name changes - change_subitem_name;
  • When an update is posted in sub-items - create_subitem_update;

📘

NOTE

Some of the events also accept the "config" field. This field is used to pass configuration for the event.

Currently, the only event that requires the config field is the change_specific_column_value() event. To use this event, pass a JSON object that contains the column ID you wish to subscribe to such as {"columnId": "status1"}.
However, using this mutation will not support subscribing to sub-item columns at this time.

mutation {
    create_webhook (board_id: 1234567, url: "https://www.webhooks.my-webhook/test", event: change_specific_column_value, config: "{\"columnId\": \"status\"}") {
        id
        board_id
    }
}
fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "mutation { create_webhook (board_id: 1234567, url: \"https://www.webhooks.my-webhook/test\", event: change_specific_column_value, config: \"{\\\"columnId\\\" : \\\"status\\\"}\") { id board_id } }"
   })
  })
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { create_webhook (board_id: 1234567, url: \"https://www.webhooks.my-webhook/test\", event: change_specific_column_value, config: "{\\\"columnId\\\": \\\"status\\\"}") { id board_id } }"}'

Sub-item Webhook notes

You can now create a webhook for sub-item events via the API. When sending a create_webhook mutation, use the Main/Parent Board ID, and a sub-item event type. Here is a list of sub-item events:

  • When a sub-item is created - create_subitem;
    • When any sub-item column changes - change_subitem_column_value;
    • When a sub-item name changes - change_subitem_name;
    • When an update is posted in sub-items - create_subitem_update;

📘

Sub-item webhook payloads

The payload you will receive from sub-item event webhooks will have the same format as a main item webhook payload. It will include the sub-item board ID, however.
You can also add a query param to your webhook URL to differentiate between sub-item and main item events, for example:

https://webhookurl.com/?createaSubItem=true

mutation {
  create_webhook (board_id: mainBoardId, url:"yourURL/?yourQueryParam", event: change_subitem_column_value) {
    id
    board_id
  }
}
​​curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: yourApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { create_webhook (board_id: 1544542904, url: \"yourWebhookUrl/?yourQueyParam\", event: change_subitem_column_value) { id board_id}}"}'
fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "mutation { create_webhook (board_id: mainBoardId, url: \"https://www.webhooks.my-webhook/test/?yourQueryParam\", event: change_subitem_column_value) { id board_id } }"
   })
  })

Arguments for Create a Webhook

The following create_webhook() arguments define the newly created webhook.

Argument

Definition

board_id !Int

The board's unique identifier.

url !String

The webhook URL.

event !WebhookEventType

The event to listen to (incoming_notification / change_column_value / change_specific_column_value / create_item / create_update / change_name / when_date_arrived)
The sub-item event to listen to (create_subitem / create_subitem_update / change_subitem_name / change_subitem_column_value)

config JSON

The webhook configuration.

Delete a Webhook

The delete webhook mutation deletes a webhook. After the mutation runs it will no longer report events to the URL given.

mutation {
    delete_webhook ( id: 12) {
        id
        board_id
    }
}
fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     query : "mutation { delete_webhook (id: 12) { id board_id } }"
   })
  })
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { delete_webhook (id: 12) { id board_id } }"}'

Arguments for Delete a Webhook

The following delete_webhook() argument determines which webhook to delete.

Argument

Definition

id !Int

The webhook's unique identifier.

Sample payload for Webhook events

Every webhook sent to your endpoint will have an event field in its body. This field will contain the payload with the event's data.

Below are a few examples of what these will look like

📘

Sub-item webhook payload

Sub-item webhooks will include a very similar payload for each event. Additionally they will also include the parent_item_id in their payload.

"event": {
  "userId": 9603417,
  "originalTriggerUuid": null,
  "boardId": 1771812698,
  "pulseId": 1772099344,
  "pulseName": "Create_item webhook",
  "groupId": "topics",
  "groupName": "Group Title",
  "groupColor": "#579bfc",
  "isTopGroup": true,
  "columnValues": {},
  "app": "monday",
  "type": "create_pulse",
  "triggerTime": "2021-10-11T09:07:28.210Z",
  "subscriptionId": 73759690,
  "triggerUuid": "b5ed2e17c530f43668de130142445cba"
 }
"event": {
  "userId": 9603417,
  "originalTriggerUuid": null,
  "boardId": 1772135370,
  "pulseId": 1772139123,
  "pulseName": "sub-item",
  "groupId": "topics",
  "groupName": "Subitems",
  "groupColor": "#579bfc",
  "isTopGroup": true,
  "columnValues": {},
  "app": "monday",
  "type": "create_pulse",
  "triggerTime": "2021-10-11T09:24:51.835Z",
  "subscriptionId": 73761697,
  "triggerUuid": "5c28578c66653a87b00a80aa4f7a6ce3",
  "parentItemId": "1771812716",
  "parentItemBoardId": "1771812698"
 }
"event": {
  "userId": 9603417,
  "originalTriggerUuid": null,
  "boardId": 1771812698,
  "groupId": "topics",
  "pulseId": 1771812728,
  "pulseName": "Crate_item webhook",
  "columnId": "date4",
  "columnType": "date",
  "columnTitle": "Date",
  "value": {
   "date": "2021-10-11",
   "icon": null,
   "time": null
  },
  "previousValue": null,
  "changedAt": 1633943701.9457765,
  "isTopGroup": true,
  "app": "monday",
  "type": "update_column_value",
  "triggerTime": "2021-10-11T09:15:03.429Z",
  "subscriptionId": 73760484,
  "triggerUuid": "645fc8d8709d35718f1ae00ceded91e9"
 }
"event": {
  "userId": 9603417,
  "originalTriggerUuid": null,
  "boardId": 1771812698,
  "pulseId": 1771812728,
  "body": "<p>create_update webhook</p>",
  "textBody": "create_update webhook",
  "updateId": 1190616585,
  "replyId": null,
  "app": "monday",
  "type": "create_update",
  "triggerTime": "2021-10-11T09:18:57.368Z",
  "subscriptionId": 73760983,
  "triggerUuid": "6119292e27abcc571f90ea4177e94973"
 }
"event": {
  "userId": 9603417,
  "originalTriggerUuid": null,
  "boardId": 1771812698,
  "groupId": "topics",
  "pulseId": 1772099344,
  "pulseName": "Create_item webhook",
  "columnId": "status",
  "columnType": "color",
  "columnTitle": "Status",
  "value": {
   "label": {
    "index": 3,
    "text": "Status change wbhook",
    "style": {
     "color": "#0086c0",
     "border": "#3DB0DF",
     "var_name": "blue-links"
    }
   },
   "post_id": null
  },
  "previousValue": null,
  "changedAt": 1633944017.473193,
  "isTopGroup": true,
  "app": "monday",
  "type": "update_column_value",
  "triggerTime": "2021-10-11T09:20:18.022Z",
  "subscriptionId": 73761176,
  "triggerUuid": "504b2eb76c80f672a18f892c0f700e41"
 }

Did this page help you?