Webhooks (also called a web callback or HTTP push API) are ways to provide real-time information and updates. They deliver data to other applications as it happens, making webhooks much more efficient for both providers and consumers.

Our webhook integration provides real-time updates from monday.com boards, making it a valuable alternative to constantly polling the API for updates. You can use it to subscribe to events on your boards and get notified by an HTTP or HTTPS post request to a specified URL with the event information as a payload.

If you're building an app for the marketplace, check out our app lifecycle webhooks guide.

Adding a webhook to a board

Follow these steps to add a webhook to one of your boards:

1. Open the Automations Center in the top right-hand corner of the board.
2. Click on Integrations at the bottom of the left-pane menu.

3. Search for webhooks and find our webhooks app.
4. Select the webhook recipe of your choosing.
5. Provide the URL that will receive the event payload. Please note that our servers will send a challenge to that URL to verify that you control this endpoint. Check out the verifying a webhook URL section for more info!

URL Verification

Your app should control the URL you specified. Our platform checks this by sending a JSON POST body containing a randomly generated token as a challenge field. We expect you to return the token as a challenge field of your response JSON body to that request.

The challenge will look something like this, and 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);})

from flask import Flask, request, abort, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    if request.method == 'POST':
        data = request.get_json()
        challenge = data['challenge']
        
        return jsonify({'challenge': challenge})

        # print(request.json)
        # return 'success', 200
    else:
        abort(400)

if __name__ == '__main__':
    app.run(debug=True)

Authenticating requests

Some webhook requests contain a JWT in the Authorization header, which can be used to check the request is legitimate. To authenticate the request, verify the JWT's signature against the app's Signing Secret, as described in our integrations documentation.

If you want to enable this feature, create the webhook with an integration app token:

1. Create a monday app & add an integration feature to it
2. Generate an OAuth token for this app
3. Call the create_webhook mutation using the OAuth token

Remove ability to turn off webhook

End-users cannot disable integration webhooks. This is so the app does not get disrupted by a curious end-user toggling a webhook on and off.

To enable this feature, make sure to create the webhook with an integration app token. Instructions to do that are in the previous section.

Retry policy

Requests sent through our webhook integration will retry once a minute for 30 minutes.

Queries

You can use the webhooks query to retrieve webhook data via the API.

• Required scope:webhooks:read

• Returns an array containing one or a collection of webhooks

• Can only be queried directly at the root; can't be nested within another query

query {
  webhooks(board_id: 1234567890){
    id
    event
    board_id
    config
  }
}

let query = 'query { webhooks (board_ids: 1234567890) { id event board_id config }}';

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     'query' : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following arguments to reduce the number of results returned in your webhooks query.

Fields

You can use the following fields to specify what information your webhooks query will return.

Mutations

The API allows you to create and delete webhooks using the following mutations.

Create a webhook

Required scope:webhooks:write

The create_webhook mutation creates a new webhook via the API. You can specify which fields to return in the mutation response. After the mutation runs, a webhook subscription will be created based on a specific event, so the webhook will send data to the subscribed URL every time the event happens on your board.

You can add a query param to your webhook URL if you want to differentiate between subitem and main item events. The URL must 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.

mutation {
  create_webhook (board_id: 1234567890, url: "https://www.webhooks.my-webhook/test/", event: change_status_column_value, config: "{\"columnId\":\"status\", \"columnValue\":{\"$any$\":true}}") {
    id
    board_id
  }
}

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : "mutation { create_webhook (board_id: 1234567890, url: \"https://www.webhooks.my-webhook/test/\", event: change_status_column_value, config: \"columnId\":\"status\", \"columnValue\":{ {\"$any$\":true}) { id board_id } }"
   })
  })

Arguments

You can use the following arguments to define the new webhook's characteristics.

Note: Some events also accept the config argument, which is used to pass the event's configuration.

Delete a webhook

Required scope:webhooks:write

The delete_webhook mutation deletes a webhook via the API. After the mutation runs, it will no longer report events to the provided URL.You can specify which fields to return in the mutation response.

mutation {
  delete_webhook (id: 12) {
    id
    board_id
  }
}

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : "mutation { delete_webhook (id: 12) { id board_id } }"
   })
  })

Arguments

You can use the following argument to specify which webhook to delete.

Sample payload for webhook events

Every webhook sent to your endpoint will have an event field containing the payload with the event's data. Subitem webhooks will include a similar payload for each event but will also include the parent_item_id and subitem board ID in their payload. You can take a deeper look into the payloads using the samples below!

"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,
  "itemId": 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"
 }

📘

Join our developer community!

We've created a community 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! 😎