1. Home
  2. Develop Docs
  3. Webhook开发文档
Searching...

Webhook开发文档

目录

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

对接准备工作

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

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

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

事件

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

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

通用

签名

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

  1. 读取 HTTP 请求的 Body，将其转换为字符串 body_str；
  2. 将 body_str 和 secret 拼接成需要加密的字符串 encrypted_str，body_str 在前， secret 在后；
  3. 对 encrypted_str 进行 SHA1 加密得到 signature_str；
  4. 将 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_idinteger企业 ID
client_infoobject联系人信息
agent_namestring客服真实姓名
agent_idinteger客服 ID
agent_nick_namestring客服昵称
agent_work_numstring客服工号
agent_accountstring客服邮箱
agent_group_namestring客服分组名称
conv_idinteger对话 ID
track_idstring对话访问标识
visit_idstring访问 ID
conv_tagsarray(string)对话标签
conv_start_timestring对话创建时间
conv_end_timestring对话结束时间
summarystring对话小结
summary_timestring对话小结时间
evaluationinteger评价类型 0-差评 1-中评 2-好评
evaluation_contentstring评价内容
source_typestring访问来源
source_urlstring来源 URL
sourcestring对话渠道
sub_sourcestring子渠道名称
visit_page_titlestring着陆页标题
visit_page_urlstring着陆页 URL
conv_titlestring对话页标题
conv_urlstring对话页 URL
search_enginestring搜索引擎
visitor_osstring操作系统
visitor_browserstring浏览器
visitor_locationstring地区
browser_languagestring浏览器语言
utm_sourcestringutm_source
utm_mediumstringutm_medium
utm_termstringutm_term
utm_contentstringutm_content
utm_campaignstringutm_campaign
messagesarray(object)对话消息列表
client_info 对象字段
字段名类型说明
contact_idstring联系人 ID
track_idsarray(string)访问标识列表
tagsarray(string)联系人标签
system_fieldsobject系统字段，只包含启用显示的字段
custom_fieldsobject自定义字段，只包含启用显示的字段
messages 对象字段
字段名类型说明
agent_namestring消息对应的接待客服真实姓名
agent_tokenstring消息对应的接待客服 token
fromstring消息来源
timestampstring消息时间
contentstring消息内容
contentstring消息内容
typestring消息类型

联系人

响应示例

{
  "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": "123@q q 。",
        "name": "aaa",
        "tel": ""
      },
      "tags": null,
      "track_ids": [
        "xxxxx"
      ]
    }
  }
}

联系人数据模型

字段名类型说明
contact_idstring联系人 ID
track_idsarray(string)访问标识列表
tagsarray(string)联系人标签
system_fieldsobject系统字段，只包含启用显示的字段
custom_fieldsobject自定义字段，只包含启用显示的字段

Updated on 2025年6月26日
Was this article helpful?
Yes No

Related Articles