Overview

A webhook is an HTTP request used to provide push notifications. LikeMinds sends webhook to update your systems about certain changes or events, such as when a user creates a conversation/post or tags someone in a chat.

To receive Likeminds webhooks, you need to set up a dedicated endpoint on your server as a webhook listener that can receive POST requests, then provide this endpoint URL to Likeminds.

Configuring Webhooks

Before you can start receiving webhooks from Likeminds, you need to follow these steps:

1. Set up a Webhook Listener: You’ll need to set up a Webhook endpoint with a valid URL which can accept POST data from incoming webhook events.
2. Create an Auth Token using an Admin/CM account:

• Call the POST /sdk/initiate link with your Admin/CM credentials:

curl --location 'https://auth.likeminds.community/sdk/initiate'
--header 'x-api-key: <YOUR API KEY>'
--data '{
    "user_name": "<Name of User>",
    "user_unique_id": "<UUID of Admin/CM>"
}' 

• Extract the access_token from the response body.

3. Register a new webhook for your Organization:

• Call the POST /webhook link to set the webhook url, status, and type:

curl --location '<https://auth.likeminds.community/webhook>'
--header 'Authorization: <auth_token>'
--data '{
    "webhook_type": "<webhook_type>",
    "url": "<your_webhook_url>",
    "is_active": true
}'

Webhook Retry Mechanism

In case of a non-200 HTTP status or timeout, LikeMinds will resend the webhook event. Here are the retry mechanism details:

• Max retries: 3
• Time interval: 1 second, 1 minute, and 1 hour.

If all three retries fail (excluding the initial trial), the webhook status will be set to inactive. You can set it back to active using the Update Webhook API.

Supported Webhook Events

Likeminds currently supports the following webhook event types:

Chat Webhooks

Webhook type	Trigger Event
chatroom.joined	A user has joined/followed a chatroom
chatroom.left	A user has left a chatroom
chatroom.user.tagged	User/s have been tagged in a chatroom conversation
chatroom.conversation.replied	A conversation in a chatroom is replied
profile.created	A new profile/user is created in the community
notifications.chat	All chat notifications sent to user
chatroom.message.sent	Chat message sent to chatroom
chatroom.message.reacted	A reaction is added to the message
chatroom.message.reaction.deleted	A reaction is deleted to the message
chatroom.message.deleted	A chatroom message is deleted
chatroom.poll.created	A chatroom poll is created

Feed Webhooks

Webhook type	Trigger Event
post.created	A new post is created
post.pinned	A post is pinned
post.liked	A post is liked by a user
post.tagged	A user is tagged in a post text
comment.added	A comment is added on a post
comment.tagged	A user is tagged in a comment text
comment.react	A user has liked/reacted on a comment
notifications.feed	All feed notifications and its payload

Webhook Payload Structure

The payload structure for each webhook event type follows a consistent format, with some variations in the data object depending on the specific event type. The general structure is as follows:

{
  "id": Event ID (string),
  "created_at": Webhook trigger time (Unix timestamp in Milliseconds) (integer),
  "event": Event name (e.g., "post.created", "chatroom.joined") (string),
  "source": Source identifier (e.g., "LM_FEED", "LM_CHAT") (string),
  "data": Event-specific data object (object),
}

Defined Object Structures:

user

{
  "user": {
    "id": User ID (integer),
    "custom_title": Custom title (string),
    "image_url": User image URL (string),
    "Is_guest": Indicates if the user is a guest (boolean),
    "is_deleted": If user is deleted (boolean),
    "name": User name (string),
    "sdk_client_info": {
      "community": Community ID (integer),
      "uuid": customer UUID (string),
    },
    "uuid": LM UUID (string),
  }
}

post

{
  "post": {
    "_id": Post ID (string),
    "attachments": Attachments of post (array),
    "comment_ids": null | comment IDs or null (array),
    "comments_count": Number of comments (integer),
    "community_id": Community ID (integer),
    "created_at": Post creation time (Unix timestamp in ms) (integer),
    "heading": Post heading (string),
    "is_edited": Indicates if the post has been edited (boolean),
    "is_liked": Indicates if the user has liked the post (boolean),
    "is_pinned": Indicates if the post is pinned (boolean),
    "is_repost": Indicates if the post is a repost (boolean),
    "is_reposted_by_user": Indicates if the post is reposted by the user (boolean),
    "is_saved": Indicates if the post is saved (boolean),
    "likes_count": Number of likes (integer),
    "menu_items": menu items (array),
    "repost_count": Number of reposts (integer),
    "text": Post text content (string),
    "topics": Topic of the post (array),
    "updated_at": Post update time (Unix timestamp in ms) (integer),
    "uuid": LM UUID (string),
  }
}

comment

{
  "comment": {
    "_id": Comment ID (string),
    "temp_id": null | Temporary ID or null (string),
    "text": Comment text (string),
    "level": Comment level (e.g., 1 for root comment, 2 for reply to a root comment, etc.) (integer),
    "uuid": UUID of the commenter (string),
    "community_id": Community ID (integer),
    "post_id": Post ID the comment belongs to (string),
    "is_liked": Indicates if the user has liked the comment (boolean),
    "likes_count": Number of likes on the comment (integer),
    "comments_count": Number of replies to the comment (integer),
    "is_edited": Indicates if the comment has been edited (boolean),
    "is_deleted": Indicates if the comment has been deleted (boolean),
    "deleted_by": User ID of the user who deleted the comment (string),
    "deleted_by_uuid": UUID of the user who deleted the comment (string),
    "delete_reason": Reason for deleting the comment (string),
    "parent_comment": CommentResponse object (recursive structure for nested comments) (object),
    "replies": Array of CommentResponse objects (replies to this comment) (array),
    "menu_items": [
      {
        "id": Menu item ID (integer),
        "title": Menu item title (string),
      }
    ],
    "created_at": Comment creation time (Unix timestamp in ms) (integer),
    "updated_at": Comment update time (Unix timestamp in ms) (integer),
  }
}

topic

{
  "topic": {
    "_id": Topic ID (string),
    "name": Topic name (string),
    "is_enabled": Indicates if the topic is enabled (string),
    "priority": Topic priority (string),
    "is_searchable": Indicates if the topic is searchable (string),
    "parent_id": Parent topic ID (string),
    "parent_name": Parent topic name (string),
    "level": Topic level (e.g., 0 for root topic, 1 for child-topic, etc.) (integer),
    "widget_id": Widget ID associated with the topic (string),
  }
}

widget

{
  "widget": {
    "_id": Widget ID (string),
    "parent_entity_id": Parent entity ID (string),
    "parent_entity_type": Parent entity type (string),
    "metadata": Key-value pairs for widget metadata (object),
    "created_at": Widget creation time (Unix timestamp in ms) (integer),
    "updated_at": Widget update time (Unix timestamp in ms) (integer),
  }
}

conversation

{
  "conversation": {
    "conversation_id": Conversation ID (string),
    "creator_id": Creator ID (string),
    "members": Array of member IDs (array),
    "message": Conversation message (string),
    "timestamp": Conversation creation time (Unix timestamp) (integer),
  }
}

chatroom

{
  "chatroom": {
    "chatroom_image_url": Chatroom image URL (string),
    "community_id": Community ID (integer),
    "community_name": Community name (string),
    "title": Chatroom title (string),
    "header": Chatroom header (string),
    "id": Chatroom ID (string),
    "is_secret": Indicates if the chatroom is secret (boolean),
    "updated_at": Chatroom update time (Unix timestamp in milliseconds) (integer),
    "created_at": Chatroom creation time (Unix timestamp in milliseconds) (integer),
    "participants_count": Number of participants in the chatroom (integer),
  }
}

Chat event payloads (data)

chatroom.joined

{
  "chatroom": Chatroom Object (object),
  "user": User Object (object),
  "join_method": How the user joined (string),
}

chatroom.user.tagged

{
  "chatroom": Chatroom Object (object),
  "conversation": Conversation Object (object),
  "created_by_user": User Object (Created By User) (object),
  "tagged_users": Array of User Objects (Tagged Users) (array),
}

chatroom.conversation.replied

{
  "chatroom": Chatroom Object (object),
  "original_conversation": Original Conversation Object (object),
  "replied_conversation": Replied Conversation Object (object),
  "original_conversation_user": User Object (Original Conversation User) (object),
  "replied_conversation_user": User Object (Replied Conversation User) (object),
}

profile.created

{
  "user": User Object (object),
}

notifications.chat

{
  "notification_payload": Notification Payload (object),
  "uuids": Customer UUIDs (Notification Receivers) (array),
}

chatroom.message.sent

{
    "chatroom": Chatroom object (object),
    "message": Message object (object),
    "sender": Sender object (object),
}

chatroom.message.reacted

{
    "chatroom": Chatroom object (object),
    "message": Message object (object),
    "reaction": Message reaction object (object),
    "reacted_by": Reacted by user object (object),
}

chatroom.message.reaction.deleted

{
    "chatroom": Chatroom object (object),
    "message": Message object (object),
    "reaction_deleted_by": Reaction deleted by user object (object),
}

chatroom.message.deleted

{
    "chatroom": Chatroom object (object),
    "message": Message object (object),
    "deleted_by": Deleted by user object (object),
}

chatroom.poll.created

{
    "chatroom": Chatroom object (object),
    "poll": Poll object (object),
    "created_by": Created by user object (object),
}

Feed event payloads (data)

post.created

{
  "post": Post Object (object),
  "topics": Topics (object),
  "widgets": Widgets (object),
  "post_creator": Post Creator (object),
}

post.pinned

{
  "post": Post Object (object),
  "topics": Topics (object),
  "widgets": Widgets (object),
  "post_creator": Post Creator (object),
  "pinned_by": User Object (Pinned By) (object),
}

post.tagged

{
  "post": Post Object (object),
  "topics": Topics (object),
  "widgets": Widgets (object),
  "post_creator": Post Creator (object),
  "tagged_users": Array of User Objects (Tagged Users) (array of objects),
}

post.liked

{
  "post": Post Object (object),
  "topics": Topics (object),
  "widgets": Widgets (object),
  "post_creator": Post Creator (object),
  "post_liked_by": User Object (User Who Liked the Post) (object),
}

comment.added

{
  "comment": Comment Object (object),
  "comment_creator": User Object (Comment Creator) (object),
  "post": Post Object (object),
  "topics": Topics (object),
  "widgets": Widgets (object),
  "post_creator": Post Creator (object),
}

comment.tagged

{
  "comment": Comment Object (object),
  "comment_creator": User Object (Comment Creator) (object),
  "post": Post Object (object),
  "topics": Topics (object),
  "widgets": Widgets (object),
  "post_creator": Post Creator (object),
  "tagged_users": Array of User Objects (Tagged Users) (array of objects),
}

comment.react

{
  "comment": Comment Object (object),
  "comment_creator": User Object (Comment Creator) (object),
  "post": Post Object (object),
  "topics": Topics (object),
  "widgets": Widgets (object),
  "post_creator": Post Creator (object),
  "liked_by_user": User Object (User Who Liked/Reacted on the Comment) (object),
}

notifications.feed

{
  "current_page": current page of uuids (integer),
  "total_pages": total pages for the uuids (integer),
  "notification_payload": Notification Payload (object),
  "uuids": Customer UUIDs (Notification Receivers) (paginated to 1000 per page) (array),
}

Webhook Access APIs

These APIs facilitate admins to fetch, create or modify existing webhooks for a community.

POST /webhook

Description: Create a new webhook

Request Body:

{
  "webhook_type": "chatroom.joined",
  "url": "<client's url where they want to receive webhook's payload>",
  "is_active": false
}

Response:

{
    "success": true,
    "data": {
        "webhook": {
            "community": 50000,
            "created_at": 1695111667877,
            "id": 14,
            "is_active": false,
            "updated_at": 1695111667877,
            "url": "https://eoja4x1itbjwnwc.m.pipedream.net",
            "webhook_type": "chatroom.joined"
        }
    }
}

GET /webhook

Description: Fetches webhook(s) details

Query Parameter:

• response_type | String | nullable

Response:

{
    "success": true,
    "data": {
        "webhooks": [
            {
                "community": 50453,
                "created_at": 1695111667877,
                "id": 14,
                "is_active": false,
                "updated_at": 1695111667877,
                "url": "https://eoja4x1itbjwnwc.m.pipedream.net",
                "webhook_type": "chatroom.joined"
            }
        ]
    }
}

GET/webhook/<webhook_id>

Description: Fetch webhook’s detail by webhook id

Response:

{
    "success": true,
    "data": {
        "webhooks": {
            "community": 50453,
            "created_at": 1695111667877,
            "id": 14,
            "is_active": false,
            "updated_at": 1695111667877,
            "url": "https://eoja4x1itbjwnwc.m.pipedream.net",
            "webhook_type": "chatroom.joined"
        }
    }
}

PATCH /webhook/<webhook_id>

Description: Update a webhook by webhook id

Request Body:

{
"url":  "https://eoja4x1itbjwnwc.m.pipedream.net",
"is_active":  true
}

Response:

{
    "success": true,
    "data": {
        "webhook": {
            "community": 50453,
            "created_at": 1695111667877,
            "id": 14,
            "is_active": true,
            "updated_at": 1695111739320,
            "url": "https://eoja4x1itbjwnwc.m.pipedream.net",
            "webhook_type": "chatroom.joined"
        }
    }
}

PATCH /webhook

Description: Update a webhook by webhook id

Request Body:

{
    "url":  "https://eo50oe7m96y6rji.m.pipedream.net",
    "webhook_statuses":  {
        // "chatroom.joined": true,
        "chatroom.message.sent":  true,
        "chatroom.message.reacted":  true,
        "chatroom.message.reaction.deleted":  true,
        "chatroom.message.deleted":  true,
        "chatroom.poll.created":  true
    }
}

Response:

{
    "success": true,
    "data": {
        "webhook": {
            "community": 50453,
            "created_at": 1695111667877,
            "id": 14,
            "is_active": true,
            "updated_at": 1695111739320,
            "url": "https://eoja4x1itbjwnwc.m.pipedream.net",
            "webhook_type": "chatroom.joined"
        }
    }
}

DEL /webhook/<webhook_id>

Description: Delete a webhook by webhook id

Response:

{
    "success": true
}

Example use cases

Use case 1:

Let’s say you want to receive a webhook whenever a user sends a conversation in a chatroom. For that, you first need to register a webhook with webhook_type = “conversation.create” using the POST /webhook Endpoint, along with a Valid URL.

Here’s an example of how you would register the webhook:

 curl --location 'https://auth.likeminds.community/webhook'\
  --header 'Authorization: <auth_token>'\
  --data '{
      "webhook_type": "conversation.create",
      "url": "<your_webhook_url>",
      "is_active": true
  }'

Once registered, Likeminds will send a POST request to your webhook URL whenever a new conversation is created in a chatroom. You can then handle the webhook payload according to your application’s requirements.

Note: If your endpoint is IP restricted, please contact backend[at]likeminds.community to whitelist the IP addresses from which the webhooks will be sent.

Use case 2:

Now suppose you need to enable or disable multiple webhook events for your registered url. To achieve this you can call the PATCH /webhook api to enable or disable your required webhook events at once.

Here’s an example of how you would register the webhook:

curl --location --request PATCH 'https://betaauth.likeminds.community/webhook' \
--header 'Authorization: <auth_token>' \
--header 'x-platform-type: dashboard' \
--header 'Content-Type: application/json' \
--data '{
    "url": "<your_registered_url>",
    "webhook_statuses": {
        "chatroom.message.sent": true,
        "chatroom.message.reacted": true,
        "chatroom.message.reaction.deleted": false,
        "chatroom.message.deleted": true,
        "chatroom.poll.created": true
    }
}'

Additional Resources

• https://docs.likeminds.community/api
• https://docs.celigo.com/hc/en-us/articles/360015827372-Create-webhook-listeners#Create-a-webhook-export(React)