Webhooks
Create webhooks using the ClickUp API.
Webhooks
Webhooks allow you to subscribe to events in your Workspace. You can create a webhook to subscribe to events from a specific location in your Workspace.
Webhooks Scope
Webhooks are created using the user's auth token and therefore are tied to the user.
If the user who created a webhook is disabled, the webhook remains but stops triggering. The system checks if the user is still part of the relevant hierarchy before triggering each webhook.
Security
ClickUp currently does not support dedicated IP addresses from which webhook events are sent.
Each webhook event is signed with a shared secret that is unique to the webhook and returned when the webhook is created. This guarantees that the event is coming from ClickUp. More under Webhook Signature.
Registering a Webhook
Webhooks registrations are created using the Create Webhook endpoint. Each registration can be configured to subscribe to one or more events and a destination URL that ClickUp will send the event to. See more under Receiving Webhook Events further down the page.
Tip
Use a service like https://smee.io/ to test webhooks easily.
You can use*
as a wildcard to subscribe to all events.
The ClickUp API v2 example app shows how to subscribe to webhooks.
Locations Filters
You can create a webhook to subscribe to events from a specific location in your Workspace.
Only one location per hierarchy level (space, folder, list, task) can be specified per webhook. The most specific location applies, so combining Space, Folder, List, or Task will subscribe to events for the lowest level of the hierarchy.
The following example subscribes to events for the List:
{
"space_id": 1234,
"list_id": 4567
}
The following example subscribes to events for the task:
{
"space_id": 1234,
"folder_id": 9876,
"list_id": 4567,
"task_id": "abc1234"
}
Receiving Webhook Events
When an event your webhook is subscribed to occurs, ClickUp sends a POST
request with event details to the URL you provided during webhook creation. If no protocol is specified, the default is https
.
Warning
Non-SSL protocols may not be supported in the future. We recommend registering your webhook using
https
.
Requests follow these criteria:
- Sent using the
POST
method. Content-Type
is alwaysapplication/json
.- Includes
webhook_id
,event
name, andresource ID
in the body. - If available, a
history_items
array will describe the event. before
andafter
are the values of the resource before and after the event.- Use
{{webhook_id}}:{{history_item_id}}
as an idempotency key.
Example Incoming Webhook Request
POST https://yourdomain.com/webhook
Content-Type: application/json
Body:
{
"event": "listUpdated",
"history_items": [
{
"id": "8a2f82db-7718-4fdb-9493-4849e67f009d",
"type": 6,
"date": "1642740510345",
...
"source": null,
"user": {
"id": 183,
"username": "John",
...
},
"before": "webhook payloads 2",
"after": "Webhook payloads round 2"
}
],
"list_id": "162641285",
"webhook_id": "7fa3ec74-69a8-4530-a251-8a13730bd204"
}
See individual webhook payloads for more details or look at the ClickUp API v2 example app on how to process incoming webhook requests.
Webhook Response Typing Notes
history_items[x].user.id
is an integer, not a string.- Unset boolean values (e.g., Custom Field checkmarks) may be
NULL
instead offalse
. - Custom Field values are not normalized; cast to the correct type as needed.
Webhook Events
Task webhooks
taskCreated
- Triggered when a new task is created.taskUpdated
- Triggered when a task is updated. Adding an attachment to a task won't trigger the taskUpdated webhook, but uploading an attachment to a task comment will.taskDeleted
- Triggered when a task is deleted.taskPriorityUpdated
- Triggered when a task's priority is updated.taskStatusUpdated
- Triggered when a task's status is updated.taskAssigneeUpdated
- Triggered when an assignee is added or removed from a task.taskDueDateUpdated
- Triggered when a task's due date is updated.taskTagUpdated
- Triggered when a tag is added or removed from a task.taskMoved
- Triggered when a task is moved to a new List.taskCommentPosted
- Triggered when a comment is added to a task.taskCommentUpdated
- Triggered when an existing comment on a task is updated.taskTimeEstimateUpdated
- Triggered when a task's time estimate is added or updated.taskTimeTrackedUpdated
- Triggered when time tracked on a task is added, updated, or deleted.
List webhooks
listCreated
- Triggered when a new List is created.listUpdated
- Triggered when an existing List is updated.listDeleted
- Triggered when a List is deleted.
Folder webhooks
folderCreated
- Triggered when a new Folder is created.folderUpdated
- Triggered when an existing Folder is updated.folderDeleted
- Triggered when a Folder is deleted.
Space webhooks
spaceCreated
- Triggered when a new Space is created.spaceUpdated
- Triggered when an existing Space is updated.spaceDeleted
- Triggered when a Space is deleted.
Goal and Target (key result) webhooks
goalCreated
- Triggered when a new Goal is created.goalUpdated
- Triggered when an existing Goal is updated.goalDeleted
- Triggered when a Goal is deleted.keyResultCreated
- Triggered when a new Target is created.keyResultUpdated
- Triggered when an existing Target is updated.keyResultDeleted
- Triggered when a Target is deleted.
View example Goal and Target payloads
Want to learn more?
- Check out this guide from Zapier.
- You can test webhooks in your browser using webhook.site.
Updated 12 days ago