Webhook Documentation

This guide provides detailed information on how to enable, configure, and utilize webhooks for the Comments extension, along with the types of events you can expect to receive notifications for.

By following the steps outlined in this documentation, you can enable, configure, and leverage webhooks to enhance the collaborative experience in your application.

Use Cases

Common use cases for Comments webhooks include:

  • Sending notifications when a thread is created, resolved, updated, or deleted.
  • Notifying users when comments are added, updated, or deleted.
  • In conjunction with the mention extension, sending emails or notifications to users when they are mentioned in comments.

Enabling Comments Webhooks

For New Users

If you signed up for your account after March 1st 2024, Comment webhooks are enabled by default. There's no additional action required on your part to start receiving Comment webhook events.

For Existing Users

If your account was created before March 1st or you're using an older version of the webhook system, you'll need to manually enable the new webhooks. Here's how:

  1. In case you’ve already implemented a previous Collaboration webhook, make sure to check the “type” and “trigger” fields when processing incoming webhooks. (Documentation)
  2. Navigate to the Collaboration settings in your account.
  3. Locate the Webhook section and click on the "Upgrade" button.

This upgrade is necessary to accommodate the introduction of multiple new events being routed to the same webhook endpoint, distinguished by a new type and trigger field.

Configuring Webhooks

To configure webhooks for Comments notifications:

  1. Navigate to the Collaboration settings in your account.
  2. Find the webhooks section and add your desired endpoint URL.

After adding your URL, the webhook is immediately live. You'll start receiving notifications for the specified events without any delay.

Webhook Events

Comments webhooks trigger notifications for a variety of events related to threads and comments within the Comments extension. Here's a breakdown of the events and their use cases:

Types of Events

  • comment.added
  • comment.updated
  • comment.deleted
  • thread.created
  • thread.resolved
  • thread.updated
  • thread.deleted

These events are triggered immediately upon the respective action occurring in the Comments, ensuring timely notifications without any grouping or delay.

Example Payloads

Below are example payloads for different types of webhook events:

Thread Created / Comment Created

{
  "trigger": "comment.added",
  "thread": {
    "id": "128ba3a9-c684-4956-8c9f-fe5dc147c7e5",
    "createdAt": "2024-03-02T22:17:51.304Z",
    "comments": [
      {
        "id": "0259e4cb-43ad-4eb2-a7e9-a7a7d5207a76",
        "createdAt": "2024-03-02T22:17:51.307Z",
        "updatedAt": "2024-03-02T22:17:51.307Z",
        "data": {
          "userName": "Cyndi Lauper",
          "userAvatar": "https://api.dicebear.com/7.x/lorelei/svg?seed=Cyndi Lauper"
        },
        "content": "Threaderstellungskommentar"
      }
    ],
    "updatedAt": "2024-03-02T22:17:51.305Z"
  },
  "comment": {
    "id": "0259e4cb-43ad-4eb2-a7e9-a7a7d5207a76",
    "createdAt": "2024-03-02T22:17:51.307Z",
    "updatedAt": "2024-03-02T22:17:51.307Z",
    "data": {
      "userName": "Cyndi Lauper",
      "userAvatar": "https://api.dicebear.com/7.x/lorelei/svg?seed=Cyndi Lauper"
    },
    "content": "Threaderstellungskommentar"
  },
  "appName": "",
  "type": "THREAD"
}

Comment Updated

{
  "trigger": "comment.updated",
  "thread": [
    {
      "id": "0259e4cb-43ad-4eb2-a7e9-a7a7d5207a76",
      "createdAt": "2024-03-02T22:17:51.307Z",
      "updatedAt": "2024-03-02T22:18:04.246Z",
      "data": {
        "userName": "Cyndi Lauper",
        "userAvatar": "https://api.dicebear.com/7.x/lorelei/svg?seed=Cyndi Lauper"
      },
      "content": "Threaderstellungskommentar (bearbeitet)"
    }
  ],
  "comment": {
    "id": "0259e4cb-43ad-4eb2-a7e9-a7a7d5207a76",
    "createdAt": "2024-03-02T22:17:51.307Z",
    "updatedAt": "2024-03-02T22:18:04.246Z",
    "data": {
      "userName": "Cyndi Lauper",
      "userAvatar": "https://api.dicebear.com/7.x/lorelei/svg?seed=Cyndi Lauper"
    },
    "content": "Threaderstellungskommentar (bearbeitet)"
  },
  "appName": "",
  "type": "THREAD"
}

Comment Deleted

{
  "trigger": "comment.deleted",
  "thread": {
    "id": "128ba3a9-c684-4956-8c9f-fe5dc147c7e5",
    "createdAt": "2024-03-02T22:17:51.304Z",
    "comments": [
      {
        "id": "0259e4cb-43ad-4eb2-a7e9-a7a7d5207a76",
        "createdAt": "2024-03-02T22:17:51.307Z",
        "updatedAt": "2024-03-02T22:18:04.246Z",
        "data": {
          "userName": "Cyndi Lauper",
          "userAvatar": "https://api.dicebear.com/7.x/lorelei/svg?seed=Cyndi Lauper"
        },
        "content": "Threaderstellungskommentar (bearbeitet)"
      }
    ],
    "updatedAt": "2024-03-02T22:17:51.305Z"
  },
  "comment": {
    "id": "1841e650-2202-42b6-a868-907fee42ccf7",
    "createdAt": "2024-03-02T22:18:20.974Z",
    "updatedAt": "2024-03-02T22:18:20.975Z",
    "data": {
      "userName": "Cyndi Lauper",
      "userAvatar": "https://api.dicebear.com/7.x/lorelei/svg?seed=Cyndi Lauper"
    },
    "content": "Zweites Kommentar, selber Thread"
  },
  "appName": "",
  "type": "THREAD"
}

Thread Deleted

{
  "trigger": "thread.deleted",
  "thread": {
    "id": "128ba3a9-c684-4956-8c9f-fe5dc147c7e5",
    "createdAt": "2024-03-02T22:17:51.304Z",
    "comments": [
      {
        "id": "0259e4cb-43ad-4eb2-a7e9-a7a7d5207a76",
        "createdAt": "2024-03-02T22:17:51.307Z",
        "updatedAt": "2024-03-02T22:18:04.246Z",
        "data": {
          "userName": "Cyndi Lauper",
          "userAvatar": "https://api.dicebear.com/7.x/lorelei/svg?seed=Cyndi Lauper"
        },
        "content": "Threaderstellungskommentar (bearbeitet)"
      }
    ],
    "updatedAt": "2024-03-02T22:18:52.050Z",
    "resolvedAt": null
  },
  "appName": "",
  "type": "THREAD"
}

Thread Resolved

{
  "trigger": "thread.resolved",
  "thread": {
    "id": "128ba3a9-c684-4956-8c9f-fe5dc147c7e5",
    "createdAt": "2024-03-02T22:17:51.304Z",
    "comments": [
      {
        "id": "0259e4cb-43ad-4eb2-a7e9-a7a7d5207a76",
        "createdAt": "2024-03-02T22:17:51.307Z",
        "updatedAt": "2024-03-02T22:18:04.246Z",
        "data": {
          "userName": "Cyndi Lauper",
          "userAvatar": "https://api.dicebear.com/7.x/lorelei/svg?seed=Cyndi Lauper"
        },
        "content": "Threaderstellungskommentar (bearbeitet)"
      }
    ],
    "updatedAt": "2024-03-02T22:18:48.531Z",
    "resolvedAt": "2024-03-02T22:18:48.531Z"
  },
  "appName": "",
  "type": "THREAD"
}

Thread Updated (i.e., Unresolved)

{
  "trigger": "thread.updated",
  "thread": {
    "id": "128ba3a9-c684-4956-8c9f-fe5dc147c7e5",
    "createdAt": "2024-03-02T22:17:51.304Z",
    "comments": [
      {
        "id": "0259e4cb-43ad-4eb2-a7e9-a7a7d5207a76",
        "createdAt": "2024-03-02T22:17:51.307Z",
        "updatedAt": "2024-03-02T22:18:04.246Z",
        "data": {
          "userName": "Cyndi Lauper",
          "userAvatar": "https://api.dicebear.com/7.x/lorelei/svg?seed=Cyndi Lauper"
        },
        "content": "Threaderstellungskommentar (bearbeitet)"
      }
    ],
    "updatedAt": "2024-03-02T22:18:52.050Z",
    "resolvedAt": null
  },
  "appName": "",
  "type": "THREAD"
}

For the complete structure and details of each event type, refer to the respective example payloads provided above.