Guides

Webhooks

Create webhooks using the ClickUp API.

Suggest Edits

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 Tied to a User

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.

Webhook Request and Response Details

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 always application/json.
  • Includes webhook_id, event, and resource ID in the body.
  • If available, a history_items array will describe the event.
  • Use {{webhook_id}}:{{history_item_id}} as an idempotency key.

Example Request

POST https://yourdomain.com/webhook
Content-Type: application/json

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 of false.
  • Custom Field values are not normalized; cast to the correct type as needed.

Events

You can include one or more events in the request body of the Create Webhook endpoint.

👍

Tip

Use a service like https://smee.io/ to test webhooks easily.
You can use * as a wildcard to subscribe to all events.

Locations

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

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.

View example task payloads

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.

View example List payloads

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.

View example Folder payloads

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.

View example Space payloads

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?

Updated 6 days ago