What can we help you with?

Webhook integration

Screen_Shot_2020-03-08_at_17.47.27.png

monday.com offers the ability to send a Webhook via our integrations, or you could even create them via the API. You can send a Webhook each time a chosen event occurs within your board. Read on to learn more.

 

What is a Webhook?

Webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A Webhook delivers data to other applications as soon as a change happens, meaning you get data immediately unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes Webhooks much more efficient for both the provider and consumer.

 

Whenever you try to create a new Webhook on monday.com, we'll send a JSON challenge to the URL you provide to verify you have control over the endpoint. Keep on reading to find out how your app should respond!

 

How to create a new Webhook 

Step 1

On your board, click the "integrations" icon and look for the "Webhooks" app in the Integrations Center.

Screen_Shot_2021-10-27_at_11.03_1.png

Once in the integration center, search and click on Webhooks as below: 

Screen_Shot_2021-10-27_at_11.06_1.png

 

Step 2

Choose the action you want to get instant payloads about:

image_5__5_.png

 

Step 3

After choosing the action you need, you will need to specify the URL. This should be a URL that can pass the JSON challenge back, and it will be the receiver of the payloads moving forward:

image_5__6_.png

And that's it! As soon as this change will happen, for example, a new item is added to your board, your endpoint will get a payload about the change. You can find some payloads further down below.

 

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);})

 

What will the event data look like?

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:
create_item - sample 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"
 }

Column value change (specific, or any column value change) - sample payload

This will include the previous value, column ID and current value.

"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"
 }

 

Create_update - sample payload:

"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"
 }

 

 

Status change - sample payload:

"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"
 }

 

 

Sub-item webhooks are almost exactly the same, but they will also include the parent_item_id in their payload. Here are some examples:

create_subitem - sample payload:

"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"
 }

 

 

More assistance

If you need help building custom integrations, we also have an option for paid assistance through our network of certified monday.com partners. If you're interested, please fill out this form and someone will be in touch shortly!

 

If you have any questions, please reach out to our team by using our contact form. We're available 24/7 and happy to help!