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 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 always application/json.
  • Includes webhook_id, event name, and resource ID in the body.
  • If available, a history_items array will describe the event.
  • before and after 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 of false.
  • 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.

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 about 1 month ago