Mixdesk Webhook Reference - Help Center

Receive and process Mixdesk data through webhooks.

Before you start

1. Go to Settings > Webhook.

Webhook settings page with Add Webhook highlighted

2. Add a webhook, select the events you need, and enter the receiving URL.

Webhook endpoint and event configuration dialog

3. After creation, use the displayed secret to verify signatures.

Configured webhook with secret field highlighted

Events

When a selected event occurs, Mixdesk sends its data to the webhook URL.

Event name	Data model
Conversation ended: conversation.closed	Conversation model
Contact created: client.created	Contact model
Contact updated: client.updated	Contact model

General requirements

Signature

Mixdesk adds the HTTP header Mixdesk-Signature to each request. Verify it as follows:

Read the HTTP request body as a string named body_str;
Concatenate body_str and secret into the string to hash, named encrypted_str, body_str first, followed by secret.
Hash encrypted_str using SHA-1 to obtain signature_str;
Compare signature_str with the HTTP header Mixdesk-Signature value.

Request method

POST

Response status

Status code	Description
200	Success: Mixdesk delivered the subscribed event to the webhook URL.

Retries

For example, ending a conversation triggers one request. If it fails, Mixdesk retries once after 60 seconds. A failed retry is not attempted again.

Conversation data

Example response

{
  "method": "POST",
  "path": "/",
  "query": {},
  "client_ip": "3.110.241.114",
  "url": "https://123wqewqe.m.pipedream.net/",
  "headers": {
    "host": "123erreet.m.pipedream.net",
    "content-length": "2002",
    "user-agent": "Go-http-client/1.1",
    "content-type": "application/json; charset=utf-8",
    "mixdesk-signature": "b6ffa50ca776147ec302da793023d43600d8ca3e"
  },
  "bodyRaw": "{\"id\":\"sub_7bc8e0479291fe6481de189c9e65d580_1750821564_0358\",\"event\":\"conversation.closed\",\"enterprise_token\":\"xxxxxx\",\"created_at\":1750821564,\"conversation\":{\"agent_email\":\"xxxxxx@mixdesk.com\",\"agent_group_name\":\"Default Group\",\"agent_id\":13,\"agent_name\":\"xxxx\",\"agent_nick_name\":\"xxxxx\",\"agent_work_num\":\"\",\"browser_language\":\"zh-CN\",\"client_info\":{\"contact_id\":\"xxxx\",\"custom_fields\":{\"number01\":null,\"option01\":null,\"options01\":null,\"test001\":null,\"time01\":null},\"system_fields\":{\"comment\":\"\",\"email\":\"\",\"name\":\"\",\"tel\":\"\"},\"tags\":null,\"track_ids\":[\"xxxxxx\"]},\"conv_end_time\":\"2025-06-2503:19:15.000147\",\"conv_id\":3604512,\"conv_start_time\":\"2025-06-2503:19:05.487927\",\"conv_tags\":null,\"conv_title\":\"\",\"conv_url\":\"xxxxx\",\"ent_id\":11,\"evaluation\":0,\"evaluation_content\":\"\",\"messages\":[{\"agent_name\":\"\",\"agent_token\":\"\",\"content\":\"aassada\",\"from\":\"client\",\"timestamp\":\"2025-06-25T03:19:05.487927\",\"type\":\"text\"},{\"agent_name\":\"xxxx\",\"agent_token\":\"xxxxxx\",\"content\":\"asdghado\",\"from\":\"agent\",\"timestamp\":\"2025-06-25T03:19:12.658771\",\"type\":\"text\"},{\"agent_name\":\"xxxxx\",\"agent_token\":\"xxxx\",\"content\":\"niih1\",\"from\":\"agent\",\"timestamp\":\"2025-06-25T03:19:15.000147\",\"type\":\"text\"}],\"search_engine\":\"\",\"source\":\"web\",\"source_type\":\"Specified source\",\"source_url\":\"\",\"sub_source\":\"\",\"summary\":\"\",\"summary_time\":\"\",\"track_id\":\"xxxxxx\",\"utm_campaign\":\"\",\"utm_content\":\"\",\"utm_medium\":\"\",\"utm_source\":\"\",\"utm_term\":\"\",\"visit_id\":\"xxxxxx\",\"visit_page_title\":\"xxxx\",\"visit_page_url\":\"xxxx\",\"visitor_browser\":\"Chrome\",\"visitor_location\":\"xxxxx\",\"visitor_os\":\"MacOSX\"}}",
  "body": {
    "id": "sub_7bc8e0479291fe6481de189c9e65d580_1750821564_0358",
    "event": "conversation.closed",
    "enterprise_token": "xxxx",
    "created_at": 1750821564,
    "conversation": {
      "agent_email": "xxxx@mixdesk.com",
      "agent_group_name": "default",
      "agent_id": 13,
      "agent_name": "xxxx",
      "agent_nick_name": "xxxx",
      "agent_work_num": "",
      "browser_language": "zh-CN",
      "client_info": {
        "contact_id": "xxxxxx",
        "custom_fields": {
          "number01": null,
          "option01": null,
          "options01": null,
          "test001": null,
          "time01": null
        },
        "system_fields": {
          "comment": "",
          "email": "",
          "name": "",
          "tel": ""
        },
        "tags": null,
        "track_ids": [
          "xxxxx"
        ]
      },
      "conv_end_time": "2025-06-25 03:19:15.000147",
      "conv_id": 3604512,
      "conv_start_time": "2025-06-25 03:19:05.487927",
      "conv_tags": null,
      "conv_title": "",
      "conv_url": "xxxxxxxxxxx",
      "ent_id": 11,
      "evaluation": 0,
      "evaluation_content": "",
      "messages": [
        {
          "agent_name": "",
          "agent_token": "",
          "content": "aassada",
          "from": "client",
          "timestamp": "2025-06-25T03:19:05.487927",
          "type": "text"
        },
        {
          "agent_name": "xxxx",
          "agent_token": "xxxx",
          "content": "asdghado",
          "from": "agent",
          "timestamp": "2025-06-25T03:19:12.658771",
          "type": "text"
        },
        {
          "agent_name": "xxxxx",
          "agent_token": "286d6b5fafe9a6ff3f5bce503612cbe7",
          "content": "niih1",
          "from": "agent",
          "timestamp": "2025-06-25T03:19:15.000147",
          "type": "text"
        }
      ],
      "search_engine": "",
      "source": "web",
      "source_type": "Specified source",
      "source_url": "",
      "sub_source": "",
      "summary": "",
      "summary_time": "",
      "track_id": "xxxxx",
      "utm_campaign": "",
      "utm_content": "",
      "utm_medium": "",
      "utm_source": "",
      "utm_term": "",
      "visit_id": "xxxxx",
      "visit_page_title": "xxxxx",
      "visit_page_url": "xxxx",
      "visitor_browser": "Chrome",
      "visitor_location": "xxxx",
      "visitor_os": "Mac OS X"
    }
  }
}

Conversation model

Field name	Type	Description
ent_id	integer	Workspace ID
client_info	object	Contact information
agent_name	string	Team member’s real name
agent_id	integer	Team member ID
agent_nick_name	string	Team member’s display name
agent_work_num	string	Employee ID
agent_account	string	Team member’s email
agent_group_name	string	Team group name
conv_id	integer	Conversation ID
track_id	string	Conversation visit identifier
visit_id	string	Visit ID
conv_tags	array(string)	Conversation tags
conv_start_time	string	Conversation creation time
conv_end_time	string	Conversation end time
conv_type	integer	Conversation type: 1 = direct message, 2 = group
summary	string	Conversation summary
summary_time	string	Summary time
evaluation	integer	Rating: 0 = negative, 1 = neutral, 2 = positive
evaluation_content	string	Rating content
source_type	string	Traffic source
source_url	string	Source URL
source	string	Conversation channel
sub_source	string	Subchannel name
sub_source_remark	string	Subchannel notes
visit_page_title	string	Landing page title
visit_page_url	string	Landing page URL
conv_title	string	Conversation page title
conv_url	string	Conversation page URL
search_engine	string	Search engine
visitor_os	string	Operating system
visitor_browser	string	Browser
visitor_location	string	Region
browser_language	string	Browser language
utm_source	string	utm_source
utm_medium	string	utm_medium
utm_term	string	utm_term
utm_content	string	utm_content
utm_campaign	string	utm_campaign
messages	array(object)	Conversation message list
source_client_info	object	Channel profile information, available for LINE, Facebook, Instagram, and Telegram.

client_info fields

Field name	Type	Description
contact_id	string	Contact ID
track_ids	array(string)	Visit identifiers
tags	array(string)	Contact tags
system_fields	object	System fields that are enabled for display
custom_fields	object	Custom fields that are enabled for display

messages fields

Field name	Type	Description
agent_name	string	Real name of the team member associated with the message
agent_token	string	Token of the team member associated with the message
from	string	Message source
timestamp	string	Message time
content	string	Message content
content	string	Message content
type	string	Message type
source_username	string	Third-party channel username (Facebook, Instagram, Telegram, LINE, WhatsApp API, WhatsApp App, or Email)
group_sender_id	string	Group user ID. Supported by WhatsApp App, LINE, and Telegram. WhatsApp App uses + followed by the phone number; other channels use the user ID.

source_client_info fields:

Field name	Type	Description
user_id	string	User ID on the third-party channel
gender	string	Gender
locale	string	Locale
timezone	int	Time zone
user_name	string	User name

Contact