How to Create and Manage Chat API Webhooks in BoldDesk

Webhooks in Chat module allow user 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

Step 1 — Open Webhook Settings

Navigate to:
Admin → Chat → Webhooks

Step 2 — Add a New Webhook

Click Add Webhook.

Step 3 — Configure Webhook Details

Fill in the fields shown:

Webhook Fields

Step 4 — Select Webhook Event Types

Choose the event(s) you want the webhook to trigger on:

Event

Supported Chat Events

Step 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

Enable Authentication

Enable authentication to ensure only authorized endpoints accept webhook requests.

Enable Signing

Enable signature verification so your endpoint can validate payload integrity.

Custom Header

Add custom headers (e.g., API keys, tokens) to secure communication with your API.

Managing Existing Webhooks in BoldDesk Chats

How to Edit a Webhook

If you need to adjust the webhook:

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

How to Deactivate a Webhook

Deactivation temporarily stops webhook deliveries without deleting the setup.

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

How to Reactivate a Webhook

To activate again:

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

How to Delete a Webhook

To permanently remove it:

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

Sample Payload for each event

{
  "EventType": "ConversationtCreated",
  "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": "ConversationtPropertyUpdated",
  "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"
  }
}

Frequently Asked Questions (FAQ)

1. What is the purpose of a webhook in BoldDesk?
To send real‑time chat or system event data to any external application for automation or integration.

2. What happens if a webhook request fails?
Webhook errors are recorded in Webhook Failure Logs for troubleshooting.

3. Does the endpoint need to be HTTPS?
Yes. BoldDesk requires a secure HTTPS destination URL.

4. Can I create multiple webhooks?
Yes. You can configure multiple webhooks for different events or brands.

Related Articles

• How to Create and Manage Webhooks in BoldDesk Tickets