Webhook开发文档

通过 Webhooks 接收Mixdesk的数据，你可以基于收到的数据做进一步处理

对接准备工作

1.点击左下角「设置」，选择 Webhook

2.添加 webhook，根据需要选择对应事件，同时输入接收 Webhook 推送的地址

3. 添加成功后，你可以看到对应密钥，可以用来做签名校验。

事件

当对应的事件被触发时，Mixdesk会向 Webhook URL 发送请求，推送对应数据。

事件名称	对应数据模型
结束对话 conversation.closed	对话数据模型
创建联系人 client.created	联系人数据模型
更新联系人client.updated	联系人数据模型

通用

签名

请求中，Mixdesk会在 HTTP Header 中增加 Mixdesk-Signature，企业需要校验该签名，以验证数据安全性，以下是签名校验的具体流程：

读取 HTTP 请求的 Body，将其转换为字符串 body_str；
将 body_str 和 secret 拼接成需要加密的字符串 encrypted_str，body_str 在前， secret 在后；
对 encrypted_str 进行 SHA1 加密得到 signature_str；
将 signature_str 和 HTTP Header 中的 Mixdesk-Signature的值进行比对。

请求方法

POST

响应状态

状态码	描述
200	成功，Mixdesk将订阅的主题成功推送到 Webhook URL

重试机制

以对话结束为例，系统将触发一次 webhook 请求。若首次请求失败，系统将在 60 秒后进行一次重试；若重试仍失败，该请求将不会再次尝试。

对话数据

响应示例

{
  "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\":\"默认分组\",\"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\":\"指定来源\",\"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": "指定来源",
      "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"
    }
  }
}

对话数据模型

字段名	类型	说明
ent_id	integer	企业 ID
client_info	object	联系人信息
agent_name	string	客服真实姓名
agent_id	integer	客服 ID
agent_nick_name	string	客服昵称
agent_work_num	string	客服工号
agent_account	string	客服邮箱
agent_group_name	string	客服分组名称
conv_id	integer	对话 ID
track_id	string	对话访问标识
visit_id	string	访问 ID
conv_tags	array(string)	对话标签
conv_start_time	string	对话创建时间
conv_end_time	string	对话结束时间
conv_type	integer	对话类型：1-私信 2-群组
summary	string	对话小结
summary_time	string	对话小结时间
evaluation	integer	评价类型 0-差评 1-中评 2-好评
evaluation_content	string	评价内容
source_type	string	访问来源
source_url	string	来源 URL
source	string	对话渠道
sub_source	string	子渠道名称
sub_source_remark	string	子渠道备注
visit_page_title	string	着陆页标题
visit_page_url	string	着陆页 URL
conv_title	string	对话页标题
conv_url	string	对话页 URL
search_engine	string	搜索引擎
visitor_os	string	操作系统
visitor_browser	string	浏览器
visitor_location	string	地区
browser_language	string	浏览器语言
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)	对话消息列表
source_client_info	object	渠道个人信息；Line、Facebook、Instagram、Telegram，会有该分类字段。

client_info 对象字段

字段名	类型	说明
contact_id	string	联系人 ID
track_ids	array(string)	访问标识列表
tags	array(string)	联系人标签
system_fields	object	系统字段，只包含启用显示的字段
custom_fields	object	自定义字段，只包含启用显示的字段

messages 对象字段

字段名	类型	说明
agent_name	string	消息对应的接待客服真实姓名
agent_token	string	消息对应的接待客服 token
from	string	消息来源
timestamp	string	消息时间
content	string	消息内容
content	string	消息内容
type	string	消息类型
source_username	string	三方渠道用户名（三方渠道指 Facebook、Instagram、Telegram、Line、WhatsApp API、WhatsApp App、Email）
group_sender_id	string	群用户 ID（Whatsapp APP、Line、Telegram 渠道支持，WhatsApp APP 群用户 ID 会显示为：+号码，其他渠道为用户 ID）

ource_client_info对象字段:

字段名	类型	说明
user_id	string	用户对于三方渠道的用户id
gender	string	性别
locale	string	所在区域语言
timezone	int	所在时区
user_name	string	用户名称

联系人

响应示例

{
  "method": "POST",
  "path": "/",
  "query": {},
  "client_ip": "3.110.241.114",
  "url": "https://ae21794766cf8e726231860a0aab57cd.m.pipedream.net/",
  "headers": {
    "host": "ae21794766cf8e726231860a0aab57cd.m.pipedream.net",
    "content-length": "457",
    "user-agent": "Go-http-client/1.1",
    "content-type": "application/json; charset=utf-8",
    "mixdesk-signature": "b2bbd002703ffb6bb0a5373eb3b5902d621f3ec3"
  },
  "bodyRaw": "{\"id\":\"sub_7bc8e0479291fe6481de189c9e65d580_1750822171_5938\",\"event\":\"client.updated\",\"enterprise_token\":\"xxxxx\",\"created_at\":1750822171,\"client\":{\"contact_id\":\"2yhv8RcDO0ZEB9aUxTkh2edknZ3\",\"custom_fields\":{\"number01\":null,\"option01\":null,\"options01\":null,\"test001\":null,\"time01\":null},\"ent_id\":11,\"system_fields\":{\"comment\":\"\",\"email\":\"123@q q 。\",\"name\":\"aaa\",\"tel\":\"\"},\"tags\":null,\"track_ids\":[\"2yhv8SfzWyWwzJUZOXJLVEAKmfP\"]}}",
  "body": {
    "id": "sub_7bc8e0479291fe6481de189c9e65d580_1750822171_5938",
    "event": "client.updated",
    "enterprise_token": "xxxxx",
    "created_at": 1750822171,
    "client": {
      "contact_id": "xxxxx",
      "custom_fields": {
        "number01": null,
        "option01": null,
        "options01": null,
        "test001": null,
        "time01": null
      },
      "ent_id": 11,
      "system_fields": {
        "comment": "",
        "email": "",
        "name": "",
        "sources": [
          {
            "source": "whatsapp",
            "sub_source": "xxx"
          }
        ],
        "tel": "+xxx"
      },
      "tags": null,
      "track_ids": [
        "xxxxx"
      ]
    }
  }
}

联系人数据模型

字段名	类型	说明
contact_id	string	联系人 ID
track_ids	array(string)	访问标识列表
tags	array(string)	联系人标签
system_fields	object	系统字段，只包含启用显示的字段
system_fields.sources	array(object)	联系人的所有渠道信息数据，合并后会有多个，不会去重
custom_fields	object	自定义字段，只包含启用显示的字段