Webhooks in Chat module allow users to send real‑time event data such as conversation updates, message events, or ticket-linked chat activity to external systems.
This enables seamless integration with:

• Automation platforms
• Internal tools
• Custom workflows
• CRM systems
• Any API‑driven application

This guide explains what webhooks are, how they work in BoldDesk, and how to create, edit, activate, deactivate, and delete webhooks for the Chats module.

What are Chat API Webhooks in BoldDesk?

A webhook is a user-defined HTTP callback triggered when a specific chat event occurs. The chat webhook sends a structured event payload (JSON) to your endpoint, and the webhook notifies your system whenever chat-related events happen such as conversation creation, updates, status changes, or messages.

Common Use Cases

• Real-time chat and ticket synchronization
• Triggering external workflows or automation rules
• Updating CRM records
• Generating alerts or notifications
• Running background jobs in third-party systems

How to Create an API Webhook for Chat Module

Follow the steps below to create an API webhook for the chat module;

1. Open Webhook Settings. Navigate to: Admin → Chat → Developer Settings → Webhooks

2. Add a New Webhook. Click Add Webhook.
   
   

   
   
   

3. Configure Webhook Details. Fill in the fields Webhook Fields shown:

   Field	Purpose
   Name & Description	A clear label and purpose for the webhook.
   Brand	The brand this webhook applies to (if multi-brand setup).
   Event	The specific Chats event that triggers the webhook.
   Destination URL (HTTPS required)	The HTTPS endpoint that receives the webhook payload.

4. Select Webhook Event Types. Choose the event(s) you want the webhook to trigger on. Below are the Supported Chat Events.

   Event Type	Description
   Conversation Created	Triggered when a new chat conversation is created.
   Conversation Deleted	Triggered when a chat conversation is deleted.
   Conversation Property Updated	Triggered when a conversation’s property changes.
   Conversation Status Changed	Triggered when status updates (Open, Closed, etc.) occur.
   Conversation Assignee Updated	Triggered when the assigned agent/group changes.
   Message Created	Triggered when a new message is added to a chat.
   Message Edit	Triggered when an existing message is modified.
   Message Deleted	Triggered when a message is deleted or withdrawn.

5. Save the Webhook. Click Add to save the configuration.
   If delivery fails due to an unreachable endpoint or wrong HTTP method, failures appear under: Audit Logs → Webhook Failure Logs

Optional Webhook Security Settings

Below are the optional webhook security settings.

Managing Existing Webhooks in BoldDesk Chats

You can manage webhooks in BoldDesk through the following ways discussed below.

Editing a Webhook

If you need to adjust the webhook:

1. Go to Admin → Chat → Developer Settings → Webhooks
2. Find the webhook
3. Click the Edit icon
4. Modify required fields
5. Click Save

Deactivating a Webhook

Deactivation temporarily stops webhook deliveries without deleting the setup.

1. Go to Admin → Chat → Developer Settings → Webhooks → Active
2. Click the Kebab icon (⁝) next to the webhook
3. Select Deactivate

Reactivating a Webhook

To activate again:

1. Go to Admin → Chat → Developer Settings → Webhooks → Inactive
2. Locate the webhook
3. Click the Kebab icon (⁝) → Activate

Deleting a Webhook

To permanently remove it:

1. Go to Admin → Chat → Developer Settings → Webhooks
2. Click the Kebab icon (⁝) next to the webhook
3. Choose Delete
   • Click Yes, Delete to confirm

Sample Payload for Each Event

{
  "EventType": "ConversationCreated",
  "EventTime": "2026-03-06T11:44:01.3176944Z",
  "ConversationId": "e9dce62b-a53c-433d-8b8c-5dc383192fc9",
  "Payload": {
    "SourceId": 1,
    "RequestedUserId": null,
    "RequestedVisitorId": "c0289709-ee0f-4c3d-8492-01d1f3d22002",
    "PriorityId": 2,
    "LastModifiedOn": "2026-03-06T11:44:01.3176944Z",
    "LastModifiedBy": 2,
    "MessageDetails": {
      "Content": "Hello",
      "CreatedAt": "2026-03-06T11:44:01.3176944Z"
    },
    "CreatedOn": "2026-03-06T11:44:01.3176944Z",
    "Category": null,
    "GroupId": null,
    "AgentId": 1043,
    "IsVerified": false,
    "LastMessageOn": "2026-03-06T11:44:01.3176944Z",
    "CustomFields": "{}",
    "Tags": [],
    "BrandId": 1
  }
}

{
  "EventType": "ConversationPropertyUpdated",
  "EventTime": "2026-03-06T11:51:56.6601207Z",
  "ConversationId": "19272062-945f-46c6-993b-87469372e971",
  "Payload": {
    "Fields": [
      {
        "NewValue": "3",
        "OldValue": "2",
        "FieldName": "Field_API_Name_1"
      },
      {
        "NewValue": "20",
        "OldValue": null,
        "FieldName": "Field_API_Name_2"
      }
    ]
  }
}

{
  "EventType": "ConversationAssigneeUpdated",
  "EventTime": "2026-03-06T11:47:15.1757813Z",
  "ConversationId": "19272062-945f-46c6-993b-87469372e971",
  "Payload": {
    "Fields": [
      {
        "NewValue": "1011",
        "OldValue": "0",
        "FieldName": "Assigned Agent"
      },
      {
        "NewValue": null,
        "OldValue": null,
        "FieldName": "Assigned Group"
      }
    ]
  }
}

{
  "EventType": "ConversationStatusChanged",
  "EventTime": "2026-03-06T11:50:55.0413332Z",
  "ConversationId": "19272062-945f-46c6-993b-87469372e971",
  "Payload": {
    "Fields": [
      {
        "NewValue": "2",
        "OldValue": "1",
        "FieldName": "Status"
      }
    ]
  }
}

{
  "EventType": "MessageCreated",
  "EventTime": "2026-03-06T11:44:04.7464282Z",
  "ConversationId": "e9dce62b-a53c-433d-8b8c-5dc383192fc9",
  "Payload": {
    "MessageContent": {
      "Message": "Hi there!",
      "TextFormat": 2,
      "Attachments": []
    },
    "Author": {
      "IsUser": false,
      "UserId": null,
      "VisitorId": null
    },
    "ChatSource": "API",
    "IsPrivate": false,
    "ExternalReferenceId": "",
    "MessageId": "c0e9a8e0-1951-11f1-a598-37018e59b03a"
  }
}

{
  "EventType": "MessageEdit",
  "EventTime": "2026-03-06T11:49:02.9018039Z",
  "ConversationId": "19272062-945f-46c6-993b-87469372e971",
  "Payload": {
    "MessageContent": {
      "Message": "Hello there!",
      "TextFormat": 3,
      "Attachments": []
    },
    "EditedById": "1011",
    "ExternalReferenceId": null,
    "MessageId": "5d9c8ef0-1952-11f1-b175-252a43d308dd"
  }
}

{
  "EventType": "MessageDeleted",
  "EventTime": "2026-03-06T11:49:58.1201873Z",
  "ConversationId": "19272062-945f-46c6-993b-87469372e971",
  "Payload": {
    "MessageId": "5d9c8ef0-1952-11f1-b175-252a43d308dd"
  }
}

Permission

To create and manage Chat API Webhooks, the user role must include both permissions in the Admin module:

• Manage Settings
• Manage Webhook
  
  
  
  
  

Troubleshooting

1. Webhooks are not being delivered

   • Confirm the webhook is in Active state (Admin → Chat → Developer Settings → Webhooks → Active).
   • Confirm the Destination URL uses HTTPS.
   • Check Audit Logs → Webhook Failure Logs for delivery errors (for example, unreachable endpoint or incorrect HTTP method).

2. Cannot create or manage webhooks
   Confirm the user role includes both Manage Settings and Manage Webhook in the Admin module.

Frequently Asked Questions

1. What does a Chat API Webhook do in BoldDesk?
   A Chat API Webhook sends a JSON payload to an external HTTPS endpoint when a selected chat event occurs (for example, conversation created or message created).

2. Does BoldDesk require HTTPS for webhook endpoints?
   Yes. The Destination URL must be HTTPS.

3. Where can I find webhook delivery failures?
   Go to Audit Logs → Webhook Failure Logs.

4. Can I create multiple webhooks for different events or brands?
   Yes. You can configure multiple webhooks and scope them by Event and Brand (in multi-brand environments).

5. Can I stop webhook deliveries without deleting the webhook?
   Yes. Use Deactivate to stop deliveries while keeping the webhook configuration.

6. Is deleting a webhook reversible?
   No. Deleting a webhook permanently removes the webhook configuration.

7. What permissions are required to manage Chat API Webhooks?
   The role must include Manage Settings and Manage Webhook in the Admin module.

8. What security controls are available for Chat API Webhooks?
   Optional controls include Enable Authentication, Enable Signing, and Custom Header. The exact authentication/signing details are not specified in the provided content.

Related Articles

1. How to Create and Manage Webhooks in BoldDesk Tickets
2. Webhook Payloads, Headers, and Event