Basic Webhooks

Set up a webhook endpoint to receive real-time notifications for the following Velt events:

Comments
Huddle
CRDT

Setting up a Webhook

To enable Webhooks go to the Configurations -> Webhook Service in the Velt Console, or click here

Webhook Auth Token

Optional security feature to authenticate webhook requests.
Set a unique auth token in your Velt console’s webhook settings.
We add this token to the Authorization header of each request as Basic YOUR_AUTH_TOKEN.
Helps you verify that requests are from Velt, not from unauthorized sources.

Endpoint URL

This is the endpoint that we will send the webhook data to. This is usually hosted on your server.

Payload Encoding

Enable Base64 encoding for webhook payloads (disabled by default).
Addresses issues with payloads containing HTML tags that may fail due to strict endpoint policies.
If enabled, ensure your server can decode Base64 encoded payloads.

Example of decoding a Base64 encoded payload:

const encodedData = "eyJ0ZXN0IjoxLCJ0ZXN0MSI6IjxkaXY+PC9kaXY+In0="
const decodedData = Buffer.from(encodedData, 'base64').toString('utf-8');
console.log(JSON.parse(decodedData));

Payload Encryption

Enable payload encryption for enhanced security (disabled by default).
Configure this option in the Velt Console.
Encryption details:
- Payload encryption: AES-256-CBC
- Key encryption: RSA with PKCS1 OAEP padding and SHA-256 hash
Public key format:
- Provide only the base64-encoded key string, without PEM headers/footers
- Recommended key size: 2048 bits
Example of setting up decryption for Node.js:

Sample Encrypted Payload
Sample Decryption Code

{
  "encryptedData": "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",
  "encryptedKey": "OzSHFXzrXFC5wDvM5NPRkriY/NaC/USvFUPE+f4NZ30tiD2qb8sJM2XT2K7uNIZ05uDLfsJ6/BbEoYC1SOPXcFJMYqRiYFiI9RWrNgR4EtPWZ84RgrmxGcZZjzSqHzjuls8g++cuqJGRV+ePbTRH+z2OuZZu0vMKZiemaZpHL46Ewi9HUnbRDXvOlKFFHmQm5tayZ7m7Mv5iu4T5R3DPEAHlZnGqtP98ToLxUJUS2Eku/iLHXRmhmZXn55Qt5GYiyss8P5/miPqJCu1QG0CStn5Nsl4KvU+I4QYAOcMFWWUAGofOwPWtt8vPh8Bx+7t7BbayKpA4ZUEWWAjC+zASxg==",
  "iv": "SHM0UHU5WXoyTG03TnExWA=="
}

    const crypto = require('crypto');

    /**
     * Decrypts the symmetric key using the provided private key.
     * @param {string} encryptedKey - Base64 encoded encrypted symmetric key
     * @param {string} privateKey - RSA private key
     * @returns {Buffer} Decrypted symmetric key
     */
    function decryptSymmetricKey(encryptedKey, privateKey) {
        try {
            const encryptedSymmetricKey = Buffer.from(encryptedKey, 'base64');
            const decryptedSymmetricKey = crypto.privateDecrypt(
                {
                    key: `-----BEGIN RSA PRIVATE KEY-----\n${privateKey}\n-----END RSA PRIVATE KEY-----`,
                    padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
                    oaepHash: 'sha256',
                },
                encryptedSymmetricKey
            );
            return decryptedSymmetricKey;
        } catch (error) {
            console.error('Error decrypting symmetric key:', error);
            throw new Error('Failed to decrypt symmetric key');
        }
    }

    /**
     * Decrypts the webhook data using the provided symmetric key and IV.
     * @param {string} encryptedWebhookData - Base64 encoded encrypted webhook data
     * @param {Buffer} symmetricKey - Decrypted symmetric key
     * @param {string} payloadIv - Base64 encoded initialization vector
     * @returns {Object} Decrypted webhook data as a JSON object
     */
    function decryptWebhookData(encryptedWebhookData, symmetricKey, payloadIv) {
        try {
            const iv = Buffer.from(payloadIv, 'base64');
            const decipher = crypto.createDecipheriv('aes-256-cbc', symmetricKey, iv);
            let decryptedData = decipher.update(encryptedWebhookData, 'base64', 'utf8');
            decryptedData += decipher.final('utf8');
            return JSON.parse(decryptedData);
        } catch (error) {
            console.error('Error decrypting webhook data:', error);
            throw new Error('Failed to decrypt webhook data');
        }
    }

    // Example usage:
    // const decryptedKey = decryptSymmetricKey(encryptedKey, privateKey);
    // const decryptedData = decryptWebhookData(encryptedWebhookData, decryptedKey, payloadIv);

Payload Schema

Default payload: WebhookV1Payload, the common fields shared across all events
- Comment Events: comment-specific fields
- Huddle Events: no additional fields
- CRDT Events: CRDT-specific fields
Encoded payload: If you have enabled payload encoding, you will receive the payload in this format: WebhookV1PayloadEncoded
Encrypted payload: If you have enabled payload encryption, you will receive the payload in this format: WebhookV1PayloadEncrypted

If you have configured notification settings, per-user notification preferences (usersOrganizationNotificationsConfig or usersDocumentNotificationsConfig) will be included in the webhook payload.

Comments Events

The Comments component will emit webhook notifications whenever an action type occurs on a comment. Payload Schema: WebhookV1Payload + Comment Events

List of Action Types

Action Type	Description
`newlyAdded`	When the first comment in a thread is added
`added`	When a new comment is added. Not used for the first comment in a thread - see `newlyAdded`
`updated`	When an existing comment content gets updated
`deleted`	When an existing comments gets deleted
`approved`	When the comment is approved by the moderator. This is only applicable if you have turned on Moderator Mode.
`assigned`	When a comment gets assigned to a user
`statusChanged`	When a comment has its status changed (e.g. in progress, resolved, opened)
`priorityChanged`	When a comment has its priority changed (e.g. P0, P1, P2 or custom set priorities)
`accessModeChanged`	When a comment is changed from private to public or vice-versa
`accepted`	When a comment gets accepted by the moderator. This is only applicable if you have turned on Moderator Mode.
`rejected`	When a comment gets rejected by the moderator. This is only applicable if you have turned on Moderator Mode.
`reactionAdded`	When a reaction is added to a comment.
`reactionDeleted`	When a reaction is removed from a comment.
`subscribed`	When a user subscribes to a comment annotation using the option in the UI.
`unsubscribed`	When a user unsubscribes from a comment annotation using the option in the UI.
`suggestionAccepted`	When a suggestion is accepted. Opt-in: disabled by default, enable it explicitly to receive this event.
`suggestionRejected`	When a suggestion is rejected. Opt-in: disabled by default, enable it explicitly to receive this event.

Sample Webhook Data

{
  "webhookId": "-Nvmw84XtUUHIsrcKAvI",
  "commentAnnotation": {
    "annotationId": "-O7Yi14ES3EPayuzQ54J",
    "annotationIndex": 20,
    "comments": [
      {
        "commentHtml": "@Jim Halpert can you take a look?",
        "commentId": 822004,
        "commentText": "@Jim Halpert can you take a look?",
        "from": {
          "clientOrganizationId": "velt-sample-app",
          "color": "#67DBF4",
          "email": "peppa.pig@velt.dev",
          "initial": "P",
          "isAdmin": false,
          "name": "Peppa Pig",
          "organizationId": "392580a690394bfadd823101f2b05513",
          "photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Fpeppa_pig.svg?alt=media&token=a9fc83f7-b347-4868-8d52-0e888f0de73a&_gl=1*jzxghx*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMTQ5LjQyLjAuMA..",
          "textColor": "#fff",
          "type": "signedIn",
          "userId": "user0",
          "userSnippylyId": "195298461116078"
        },
        "lastUpdated": "2024-09-24T11:08:49.724Z",
        "status": "added",
        "taggedUserContacts": [
          {
            "contact": {
              "email": "jim.halpert@dundermifflin.com",
              "initial": "J",
              "name": "Jim Halpert",
              "photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Frosy_rabbit.svg?alt=media&token=4e65a9e3-080d-4416-839d-e761b6b37181&_gl=1*156om5t*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMjUzLjYwLjAuMA..",
              "userId": "e54d19af-0e43-4364-819f-0a8b18a280fb",
              "userSnippylyId": "5236622904561187"
            },
            "text": "@Jim Halpert",
            "userId": "e54d19af-0e43-4364-819f-0a8b18a280fb"
          }
        ],
        "to": [
          {
            "email": "jim.halpert@dundermifflin.com",
            "initial": "J",
            "name": "Jim Halpert",
            "photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Frosy_rabbit.svg?alt=media&token=4e65a9e3-080d-4416-839d-e761b6b37181&_gl=1*156om5t*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMjUzLjYwLjAuMA..",
            "userId": "e54d19af-0e43-4364-819f-0a8b18a280fb",
            "userSnippylyId": "5236622904561187"
          }
        ],
        "type": "text"
      },
      {
        "commentHtml": "test",
        "commentId": 719893,
        "commentText": "test",
        "from": {
          "clientOrganizationId": "velt-sample-app",
          "color": "#2c83fc",
          "email": "freddy.froglet@velt.dev",
          "initial": "F",
          "isAdmin": false,
          "name": "Freddy Froglet",
          "organizationId": "392580a690394bfadd823101f2b05513",
          "photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Ffreddy_froglet.svg?alt=media&token=e3b2e292-6480-4507-9da3-21a62a1346d4&_gl=1*s4yycs*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMDQzLjcuMC4w",
          "textColor": "#fff",
          "type": "signedIn",
          "userId": "user8",
          "userSnippylyId": "4291391246842733"
        },
        "lastUpdated": "2024-09-24T11:11:58.344Z",
        "status": "added",
        "type": "text"
      }
    ],
    "from": {
      "clientOrganizationId": "velt-sample-app",
      "color": "#67DBF4",
      "email": "peppa.pig@velt.dev",
      "initial": "P",
      "isAdmin": false,
      "name": "Peppa Pig",
      "organizationId": "392580a690394bfadd823101f2b05513",
      "photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Fpeppa_pig.svg?alt=media&token=a9fc83f7-b347-4868-8d52-0e888f0de73a&_gl=1*jzxghx*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMTQ5LjQyLjAuMA..",
      "textColor": "#fff",
      "type": "signedIn",
      "userId": "user0",
      "userSnippylyId": "195298461116078"
    },
    "lastUpdated": 1727176311596,
    "metadata": {
      "apiKey": "AN5s6iaYIuLLXul0X4zf",
      "documentId": "toolbar",
      "organizationId": "velt-sample-app"
    },
    "pageInfo": {
      "baseUrl": "https://velt-vercel-style-toolbar-demo.vercel.app",
      "commentUrl": "https://velt-vercel-style-toolbar-demo.vercel.app/?scommentId=-O7Yi14ES3EPayuzQ54J",
      "deviceInfo": {
        "browserName": "Chrome",
        "browserVersion": "128",
        "deviceType": "Mobile",
        "orientation": "landscape",
        "osName": "Macintosh",
        "osVersion": "10.15.7",
        "screenHeight": 900,
        "screenWidth": 1440,
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
      },
      "path": "/",
      "screenWidth": 804,
      "title": "Web App | Velt Demo",
      "url": "https://velt-vercel-style-toolbar-demo.vercel.app/"
    },
    "status": {
      "color": "#625DF5",
      "id": "OPEN",
      "lightColor": "#E7E8FA",
      "name": "Open",
      "svg": "\n      <svg\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 16 16\"\n        fill=\"none\"\n        xmlns=\"http://www.w3.org/2000/svg\"\n      >\n        <path\n          fill-rule=\"evenodd\"\n          clip-rule=\"evenodd\"\n          d=\"M8.00016 13.3333C10.9457 13.3333 13.3335 10.9455 13.3335 8.00001C13.3335 5.05449 10.9457 2.66668 8.00016 2.66668C5.05464 2.66668 2.66683 5.05449 2.66683 8.00001C2.66683 10.9455 5.05464 13.3333 8.00016 13.3333ZM8.00016 14.6667C11.6821 14.6667 14.6668 11.6819 14.6668 8.00001C14.6668 4.31811 11.6821 1.33334 8.00016 1.33334C4.31826 1.33334 1.3335 4.31811 1.3335 8.00001C1.3335 11.6819 4.31826 14.6667 8.00016 14.6667Z\"\n          fill=\"currentColor\"\n        />\n      </svg>\n      ",
      "type": "default"
    },
    "subscribedUsers": {
      "3604c43f40557d7aa27ff4d0f72202a3": {
        "type": "auto",
        "user": {
          "email": "jim.halpert@dundermifflin.com",
          "initial": "J",
          "name": "Jim Halpert",
          "photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Frosy_rabbit.svg?alt=media&token=4e65a9e3-080d-4416-839d-e761b6b37181&_gl=1*156om5t*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMjUzLjYwLjAuMA..",
          "userId": "e54d19af-0e43-4364-819f-0a8b18a280fb",
          "userSnippylyId": "5236622904561187"
        }
      },
      "3d517fe6ebab7b8cfcf98db6259c8a59": {
        "type": "auto",
        "user": {
          "clientOrganizationId": "velt-sample-app",
          "color": "#67DBF4",
          "email": "peppa.pig@velt.dev",
          "initial": "P",
          "isAdmin": false,
          "name": "Peppa Pig",
          "organizationId": "392580a690394bfadd823101f2b05513",
          "photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Fpeppa_pig.svg?alt=media&token=a9fc83f7-b347-4868-8d52-0e888f0de73a&_gl=1*jzxghx*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMTQ5LjQyLjAuMA..",
          "textColor": "#fff",
          "type": "signedIn",
          "userId": "user0",
          "userSnippylyId": "195298461116078"
        }
      },
      "7668f673d5669995175ef91b5d171945": {
        "type": "manual",
        "user": {
          "clientOrganizationId": "velt-sample-app",
          "color": "#2c83fc",
          "email": "freddy.froglet@velt.dev",
          "initial": "F",
          "isAdmin": false,
          "name": "Freddy Froglet",
          "organizationId": "392580a690394bfadd823101f2b05513",
          "photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Ffreddy_froglet.svg?alt=media&token=e3b2e292-6480-4507-9da3-21a62a1346d4&_gl=1*s4yycs*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMDQzLjcuMC4w",
          "textColor": "#fff",
          "type": "signedIn",
          "userId": "user8",
          "userSnippylyId": "4291391246842733"
        }
      }
    },
    "type": "comment"
  },
  "targetComment": {
    "commentHtml": "test",
    "commentId": 719893,
    "commentText": "test",
    "from": {
      "clientOrganizationId": "velt-sample-app",
      "color": "#2c83fc",
      "email": "freddy.froglet@velt.dev",
      "initial": "F",
      "isAdmin": false,
      "name": "Freddy Froglet",
      "organizationId": "392580a690394bfadd823101f2b05513",
      "photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Ffreddy_froglet.svg?alt=media&token=e3b2e292-6480-4507-9da3-21a62a1346d4&_gl=1*s4yycs*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMDQzLjcuMC4w",
      "textColor": "#fff",
      "type": "signedIn",
      "userId": "user8",
      "userSnippylyId": "4291391246842733"
    },
    "lastUpdated": "2024-09-24T11:11:58.344Z",
    "status": "added",
    "type": "text"
  },
  "actionType": "added",
  "notificationSource": "comment",
  "actionUser": {
    "clientOrganizationId": "velt-sample-app",
    "color": "#2c83fc",
    "email": "freddy.froglet@velt.dev",
    "initial": "F",
    "isAdmin": false,
    "name": "Freddy Froglet",
    "organizationId": "392580a690394bfadd823101f2b05513",
    "photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Ffreddy_froglet.svg?alt=media&token=e3b2e292-6480-4507-9da3-21a62a1346d4&_gl=1*s4yycs*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMDQzLjcuMC4w",
    "textColor": "#fff",
    "type": "signedIn",
    "userId": "user8",
    "userSnippylyId": "4291391246842733"
  },
  "metadata": {
    "apiKey": "AN5s6iaYIuLLXul0X4zf",
    "clientDocumentId": "toolbar",
    "clientOrganizationId": "velt-sample-app",
    "documentId": "toolbar",
    "documentName": "Your_Document_Name",
    "organizationId": "velt-sample-app",
    "pageInfo": {
      "baseUrl": "https://velt-vercel-style-toolbar-demo.vercel.app",
      "path": "/",
      "title": "Web App | Velt Demo",
      "url": "https://velt-vercel-style-toolbar-demo.vercel.app/"
    }
  },
  "platform": "sdk",
  "usersOrganizationNotificationsConfig": {
    "user0": {
      "inbox": "ALL",
      "email": "MINE"
    },
    "user8": {
      "inbox": "NONE",
      "email": "ALL"
    }
  }
}

Comment Visibility

Comment notification webhooks respect the comment’s visibility. When a comment is private, users who cannot see it are listed in accessDeniedUsers. Drop those users from your own fan-out. accessDeniedUsers covers two independent sources:

Users denied by your Permission Provider.
Users denied by the comment’s visibility.

In both cases the entries are client user IDs. The comment author and any user or organization named in the comment’s visibility normally receive the notification. This applies to every comment action type, including deleted. Notifications for private comments also carry a visibility object that mirrors the comment’s visibility settings.

Property	Type	Required	Description
`type`	`'public' \| 'organizationPrivate' \| 'restricted'`	No	Visibility level of the comment.
`userIds`	`string[]`	No	Client user IDs allowed to see the comment. Usually present when `type` is `restricted`.
`organizationIds`	`string[]`	No	Client organization IDs allowed to see the comment. Usually present when `type` is `organizationPrivate`.
`organizationId`	`string`	No	Single client organization ID. Treated as a one item `organizationIds` list.

Payload excerpt

{
  "actionType": "added",
  "notificationSource": "comment",
  "visibility": {
    "type": "restricted",
    "userIds": ["user0", "user8"]
  },
  "accessDeniedUsers": ["user3"]
}

Public comments carry no visibility key, and neither do notifications created before this release. Existing consumers keep working unchanged. No integration change required. Treat visibility and accessDeniedUsers as informational. Velt re-verifies comment visibility on the server before it sends the webhook. Do not use these fields to widen who you forward a notification to. For advanced (V2) webhooks, see Comment Visibility.

Huddle Events

The Huddle component will emit webhook notifications when a user creates or joins a group huddle. Payload Schema: WebhookV1Payload + Huddle Events

List of Action Types

Action Type	Description
`created`	When a `User` created a `Huddle`
`join`	When a `User` joins a `Huddle`

Huddle Created
Huddle Joined

{
  "webhookId": "-Nvmw84XtUUHIsrcKAvI",
  "actionType": "created",
  "notificationSource": "huddle",
  "actionUser": {
    "clientOrganizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
    "color": "#19bcfe",
    "email": "john@trysnippyly.com",
    "organizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
    "name": "John Smith",
    "plan": "free",
    "type": "signedIn",
    "userId": "1",
  },
  "metadata": {
    "apiKey": "Emcfab4ysRXaC1CZ8hmG",
    "clientDocumentId": "12-4-24",
    "documentId": "1856907974154638",
    "locations": {
      "5638605251172150": {
        "location": {
          "id": "location1",
          "locationName": "Location 1"
        },
        "locationId": 5638605251172150,
        "pageInfo": {
          "baseUrl": "http://localhost:3000",
          "path": "/",
          "title": "Velt React Demo",
          "url": "http://localhost:3000/"
        }
      }
    },
    "pageInfo": {
      "baseUrl": "http://localhost:3000",
      "path": "/",
      "title": "Velt React Demo",
      "url": "http://localhost:3000/"
    }
  },
  "platform": "sdk"
}

{
  "webhookId": "-Nvmw84XtUUHIsrcKAvI",
  "actionType": "joined",
  "notificationSource": "huddle",
  "actionUser": {
    "clientOrganizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
    "color": "#ff7162",
    "contacts": [
      {
        "email": "john@trysnippyly.com",
        "name": "John Smith",
        "userId": "1"
      },
      {
        "email": "sarah@trysnippyly.com",
        "name": "Sarah Wilson",
        "userId": "3"
      }
    ],
    "email": "maria@trysnippyly.com",
    "organizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
    "name": "Maria Garcia",
    "plan": "paid",
    "type": "signedIn",
    "userId": "2",
  },
  "metadata": {
    "apiKey": "Emcfab4ysRXaC1CZ8hmG",
    "clientDocumentId": "12-4-24",
    "documentId": "1856907974154638",
    "pageInfo": {
      "baseUrl": "http://localhost:3000",
      "path": "/",
      "title": "Velt React Demo",
      "url": "http://localhost:3000/"
    }
  },
  "platform": "sdk"
}

CRDT Events

The CRDT component will emit webhook notifications when data changes occur. Webhooks are enabled by default with a 5-second debounce. Payload Schema: WebhookV1Payload + CRDT Events

Learn how to configure CRDT webhooks in the CRDT Core Setup documentation.

Action Type

Action Type	Description
`updateData`	When CRDT data is updated

Sample Webhook Data

{
  "actionType": "updateData",
  "notificationSource": "crdt",
  "actionUser": {
    "organizationId": "9eab9b808921fa1c682be3516bb49ab3",
    "userSnippylyId": "6171441707478284",
    "color": "#ffcb00",
    "initial": "M",
    "clientUserName": "Michael Scott",
    "name": "Michael Scott",
    "clientOrganizationId": "crdt-array-demo-org1",
    "name_lowercase": "michaelscott",
    "email_lowercase": "michael.scott@dundermifflin.com",
    "textColor": "#FFFFFF",
    "userId": "michael",
    "email": "michael.scott@dundermifflin.com",
    "photoUrl": null,
    "isAdmin": false,
    "type": "signedIn",
    "contacts": []
  },
  "metadata": {
    "apiKey": "VKabul7W2DJhLu1BiMaj",
    "clientDocumentId": "crdt-array-demo-doc-1",
    "clientOrganizationId": "crdt-array-demo-org1",
    "documentId": "crdt-array-demo-doc-1",
    "documentMetadata": {
      "apiKey": "VKabul7W2DJhLu1BiMaj",
      "clientDocumentId": "crdt-array-demo-doc-1",
      "clientOrganizationId": "crdt-array-demo-org1",
      "documentId": "crdt-array-demo-doc-1",
      "documentName": "CRDT Array Demo",
      "organizationId": "crdt-array-demo-org1",
      "pageInfo": {
        "baseUrl": "http://localhost:5225",
        "path": "/",
        "queryParams": "",
        "title": "CRDT Array Demo",
        "url": "http://localhost:5225/"
      }
    },
    "documentName": "CRDT Array Demo",
    "organizationId": "crdt-array-demo-org1",
    "organizationMetadata": {
      "apiKey": "VKabul7W2DJhLu1BiMaj",
      "clientOrganizationId": "crdt-array-demo-org1",
      "organizationId": "crdt-array-demo-org1"
    },
    "pageInfo": {
      "baseUrl": "http://localhost:5225",
      "path": "/",
      "queryParams": "",
      "title": "CRDT Array Demo",
      "url": "http://localhost:5225/"
    }
  },
  "platform": "sdk",
  "crdtData": {
    "data": [
      {
        "completed": false,
        "id": "seed-1",
        "text": "Welcome Todo - Edit me!"
      },
      {
        "completed": false,
        "id": "bmg6tpj7we",
        "text": "Todo1"
      },
      {
        "completed": false,
        "id": "dt0vhs2t3os",
        "text": "Todo2"
      }
    ],
    "id": "crdt-array-demo-todos-1",
    "lastUpdate": "2026-03-17T06:23:24.514Z",
    "lastUpdatedBy": "michael",
    "sessionId": "tvLupvP0L2jiztlba4P0"
  },
  "webhookId": "-OnuSfG_ffGIwNkodE2a",
  "accessDeniedUsers": []
}

Get Started

Agentic Setup

Key Concepts

Async Collaboration

Realtime Collaboration

AI

Self Hosting

Backend SDKs

Model Context Protocol

Webhooks

Security

Miscellaneous

Basic Webhooks

Setting up a Webhook

Webhook Auth Token

Endpoint URL

Payload Encoding

Payload Encryption

Payload Schema

Comments Events

List of Action Types

Comment Visibility

Huddle Events

List of Action Types

CRDT Events

Action Type

​Setting up a Webhook

​Webhook Auth Token

​Endpoint URL

​Payload Encoding

​Payload Encryption

​Payload Schema

​Comments Events

​List of Action Types

​Comment Visibility

​Huddle Events

​List of Action Types

​CRDT Events

​Action Type

Setting up a Webhook

Webhook Auth Token

Endpoint URL

Payload Encoding

Payload Encryption

Payload Schema

Comments Events

List of Action Types

Comment Visibility

Huddle Events

List of Action Types

CRDT Events

Action Type