The ClickUp Webhooks API enables developers to subscribe to real-time events within a Workspace. When subscribed events occur, ClickUp sends HTTP POST requests to a specified endpoint URL with event details. Webhooks support events for tasks, lists, folders, spaces, and goals. Each webhook payload is signed with a shared secret for verification, ensuring the event originated from ClickUp.
openapi: 3.1.0
info:
title: ClickUp Webhooks API
description: >-
The ClickUp Webhooks API enables developers to subscribe to real-time
events within a Workspace. When subscribed events occur, ClickUp sends
HTTP POST requests to a specified endpoint URL with event details.
Webhooks support events for tasks, lists, folders, spaces, and goals.
Each webhook payload is signed with a shared secret for verification,
ensuring the event originated from ClickUp.
version: '2.0'
contact:
name: ClickUp Support
url: https://help.clickup.com
termsOfService: https://clickup.com/terms
externalDocs:
description: ClickUp Webhooks Documentation
url: https://developer.clickup.com/docs/webhooks
servers:
- url: https://api.clickup.com/api/v2
description: ClickUp API v2 Production Server
tags:
- name: Webhooks
description: >-
Operations for creating, retrieving, updating, and deleting webhook
subscriptions.
security:
- bearerAuth: []
paths:
/team/{team_id}/webhook:
get:
operationId: getWebhooks
summary: Get webhooks
description: >-
Retrieves all webhook subscriptions for a Workspace. Returns
webhook details including the endpoint URL, subscribed events,
status, and health information.
tags:
- Webhooks
parameters:
- $ref: '#/components/parameters/teamId'
responses:
'200':
description: Successfully retrieved webhooks
content:
application/json:
schema:
type: object
properties:
webhooks:
type: array
items:
$ref: '#/components/schemas/Webhook'
'401':
description: Unauthorized
post:
operationId: createWebhook
summary: Create a webhook
description: >-
Creates a new webhook subscription for a Workspace. The webhook
can be configured to listen for specific events and send notifications
to a specified endpoint URL. A shared secret is returned for
signature verification of incoming webhook payloads.
tags:
- Webhooks
parameters:
- $ref: '#/components/parameters/teamId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookRequest'
responses:
'200':
description: Webhook created successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the webhook.
webhook:
$ref: '#/components/schemas/Webhook'
'400':
description: Bad request
'401':
description: Unauthorized
/webhook/{webhook_id}:
put:
operationId: updateWebhook
summary: Update a webhook
description: >-
Updates an existing webhook subscription. The endpoint URL,
subscribed events, and status can be modified.
tags:
- Webhooks
parameters:
- $ref: '#/components/parameters/webhookId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWebhookRequest'
responses:
'200':
description: Webhook updated successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the webhook.
webhook:
$ref: '#/components/schemas/Webhook'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Webhook not found
delete:
operationId: deleteWebhook
summary: Delete a webhook
description: >-
Permanently deletes a webhook subscription. ClickUp will stop
sending events to the endpoint URL immediately.
tags:
- Webhooks
parameters:
- $ref: '#/components/parameters/webhookId'
responses:
'200':
description: Webhook deleted successfully
'401':
description: Unauthorized
'404':
description: Webhook not found
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
ClickUp personal API token or OAuth access token.
parameters:
teamId:
name: team_id
in: path
required: true
description: >-
The unique identifier of the Workspace (team).
schema:
type: integer
webhookId:
name: webhook_id
in: path
required: true
description: >-
The unique identifier of the webhook.
schema:
type: string
schemas:
Webhook:
type: object
description: >-
A webhook subscription object.
properties:
id:
type: string
description: >-
The unique identifier of the webhook.
userid:
type: integer
description: >-
The user ID who created the webhook.
team_id:
type: integer
description: >-
The Workspace ID the webhook belongs to.
endpoint:
type: string
format: uri
description: >-
The URL that ClickUp sends event payloads to.
client_id:
type: string
nullable: true
description: >-
The OAuth client ID if the webhook was created via OAuth.
events:
type: array
items:
type: string
enum:
- taskCreated
- taskUpdated
- taskDeleted
- taskPriorityUpdated
- taskStatusUpdated
- taskAssigneeUpdated
- taskDueDateUpdated
- taskTagUpdated
- taskMoved
- taskCommentPosted
- taskCommentUpdated
- taskTimeEstimateUpdated
- taskTimeTrackedUpdated
- listCreated
- listUpdated
- listDeleted
- folderCreated
- folderUpdated
- folderDeleted
- spaceCreated
- spaceUpdated
- spaceDeleted
- goalCreated
- goalUpdated
- goalDeleted
- keyResultCreated
- keyResultUpdated
- keyResultDeleted
description: >-
The events the webhook is subscribed to.
task_id:
type: string
nullable: true
description: >-
Optional task ID to scope webhook events to a specific task.
list_id:
type: integer
nullable: true
description: >-
Optional list ID to scope webhook events to a specific list.
folder_id:
type: integer
nullable: true
description: >-
Optional folder ID to scope webhook events to a specific folder.
space_id:
type: integer
nullable: true
description: >-
Optional space ID to scope webhook events to a specific space.
health:
type: object
properties:
status:
type: string
description: >-
The health status of the webhook (active, failing, etc.).
fail_count:
type: integer
description: >-
Number of consecutive failures.
description: >-
Health status of the webhook.
secret:
type: string
description: >-
The shared secret for HMAC-SHA256 signature verification.
Only returned when the webhook is first created.
CreateWebhookRequest:
type: object
required:
- endpoint
- events
description: >-
Request body for creating a new webhook subscription.
properties:
endpoint:
type: string
format: uri
description: >-
The URL to send webhook event payloads to.
events:
type: array
items:
type: string
description: >-
Array of event names to subscribe to. Use '*' to subscribe
to all events.
task_id:
type: string
description: >-
Optional task ID to scope webhook events to a specific task.
list_id:
type: integer
description: >-
Optional list ID to scope webhook events to a specific list.
folder_id:
type: integer
description: >-
Optional folder ID to scope webhook events to a specific folder.
space_id:
type: integer
description: >-
Optional space ID to scope webhook events to a specific space.
UpdateWebhookRequest:
type: object
description: >-
Request body for updating an existing webhook subscription.
properties:
endpoint:
type: string
format: uri
description: >-
The updated endpoint URL.
events:
type: array
items:
type: string
description: >-
Updated array of event names to subscribe to.
status:
type: string
enum:
- active
- inactive
description: >-
Set the webhook status to active or inactive.