Webhook signature

All requests sent to your webhook endpoints are signed to ensure you can verify that the traffic is genuinely coming from ClickUp.

We use a hash-based message authentication code (HMAC) to sign requests.

When creating a webhook, the webhook.secret is returned in the response object. Each incoming webhook request to your server will use this secret to generate a signature.

This signature is included in the X-Signature HTTP header, allowing the client to verify it was created using the same secret.

Note

Signatures are always digested in hexadecimal format.

Example webhook request

Header

Copy

Copied

Content-Type: application/json
X-Signature: f7bc83f430538424b13298e6aa6

Body

Copy

Copied

{
    "webhook_id": "7689a169-a000-4985-8676-6902b96d6627",
    "event": "taskCreated",
    "task_id": "c0j"
}

The X-Signature value in this example was created by hashing the request body using the provided secret and the SHA-256 algorithm.

To verify the signature, the client can generate a hash signature using the same algorithm and secret, and compare the values.

Example using Node.js:

Below is a Node.js example for verifying the signature. For examples in other languages, see this repository.

Note

In this example, the body is already a string. If you are using an HTTP client that automatically parses request bodies, make sure to stringify the object without adding white spaces.

Copy

Copied

const crypto = require('crypto');

const key = 'secret'; // from the webhook object, stored in your DB
const body = '{"webhook_id":"7689a169-a000-4985-8676-6902b96d6627","event":"taskCreated","task_id":"c0j"}';

const hash = crypto.createHmac('sha256', key).update(body);
const signature = hash.digest('hex');