5 min read
Feature
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.
Once in the Integrations Center, search and click on Webhooks as shown below:
Step 2
Choose the action you want to get instant payloads about:
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:
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.
Step 4
Add a description to detail how your Webhook integration is being used in your workflow. This will allow any user using this integration to better understand what is the purpose of this integration and how it plugs into the workflow.
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.
{
"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 right here. We’re available 24/7 and happy to help.
Comments