版本：v2.0

查询企微消息回调记录

查询企业微信推送到平台的事件回调报文记录。企业微信向平台推送的原始回调报文会逐条落库，本接口把原始报文解析成 JSON 对象后，连同落库时提取的事件类型、变更类型、变更详情等字段一起返回，支持按落库时间区间、事件类型、变更类型、变更详情筛选，分页输出。

信息

与「回调通知」的区别：本分类的接口查询的是企业微信直接推送到平台的事件记录（如客户群变更、外部联系人变更）；侧栏「回调通知」分类是平台主动推送给友商的业务事件，两者方向与来源均不同，请勿混淆。

GET/api/getQiyeCallbackMsgList

核心语义

只读查询：仅查询已落库的回调记录，不改动任何数据；每次企业微信推送都会新增一条记录。
原始报文原样透出：data 字段为解析后的企业微信原始报文体，字段采用企微命名风格（ToUserName、Event 等），大部分数值型字段以字符串形式返回（如 MemChangeCnt: "1"），请做好兼容。
筛选参数全部可选：不传任何筛选条件即查询全量记录（按分页）；event / changetype / detail 按落库字段精确匹配，时间区间按落库时间过滤。
排序：按落库时间、记录 ID 倒序（最新的在前）。
解析兜底：个别记录的原始报文无法解析为 JSON 时，该条 data 回落为原始字符串。
契约：code 恒为 0；成功时 msg 为空；失败时 msg 非空、data 为空数组。业务成功与否以 msg 判定。

请求参数

名称	类型	描述	是否必填	默认值	备注
token	String	身份校验令牌	必填	-	由获取访问令牌获得
starttime	String	落库时间筛选起点	选填	不限	支持秒级/毫秒级时间戳、`YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss`；闭区间
endtime	String	落库时间筛选终点	选填	不限	写法同 `starttime`；仅给到日期时自动含当天全天（至 `23:59:59`）；闭区间
event	String	事件类型	选填	不筛选	对应报文 `Event`，如 `change_external_chat`（客户群变更）、`change_external_contact`（外部联系人变更）
changetype	String	变更类型	选填	不筛选	对应报文 `ChangeType`，如 `create` / `update` / `dismiss`
detail	String	变更详情	选填	不筛选	对应报文 `UpdateDetail`，如 `add_member` / `del_member` / `change_owner` / `change_name` / `change_notice`
pageNum	Number	页码	选填	`1`	从 1 开始
pageSize	Number	每页条数	选填	`20`	最大 `100`（超出按 `100` 返回；传 `0` 或负数按 `20` 处理）

CURL

V1（GET）

curl --location --request GET 'https://open.xinduobang.cn/api/getQiyeCallbackMsgList?token=YOUR_TOKEN&event=change_external_chat&pageSize=2'

V1（POST）

curl --location --request POST 'https://open.xinduobang.cn/api/getQiyeCallbackMsgList' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'starttime=2026-11-01' \
--data-urlencode 'endtime=2026-11-09' \
--data-urlencode 'event=change_external_chat' \
--data-urlencode 'changetype=update' \
--data-urlencode 'detail=del_member' \
--data-urlencode 'pageNum=1' \
--data-urlencode 'pageSize=20'

V2（appid 为 `V2` 版本）

curl --location --request POST 'https://open.xinduobang.cn/api/getQiyeCallbackMsgList' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-Timestamp: 1770000000' \
--header 'X-Nonce: 3f9c1a7b2e6d4058' \
--header 'X-Signature: <computed_hmac_sha256>' \
--data-urlencode 'token=YOUR_TOKEN' \
--data-urlencode 'event=change_external_chat' \
--data-urlencode 'pageNum=1' \
--data-urlencode 'pageSize=20'

信息

V2 签名算法及 X-Signature 计算方式见 V2 接入示例。

成功响应

{
  "code": 0,
  "msg": "",
  "data": {
    "total": 138,
    "pageNum": 1,
    "pageSize": 2,
    "list": [
      {
        "id": 90211,
        "addtime": 1793959863,
        "addtime_str": "2026-11-06 18:11:03",
        "event": "change_external_chat",
        "changetype": "update",
        "detail": "del_member",
        "userid": "",
        "external_userid": "",
        "data": {
          "ToUserName": "wwxxxxxxxxxxxxxxxx",
          "FromUserName": "sys",
          "CreateTime": "1793959863",
          "MsgType": "event",
          "Event": "change_external_chat",
          "ChatId": "wrj8xBDgAAzy3EnJfeGffnItxKvp3RZA",
          "ChangeType": "update",
          "UpdateDetail": "del_member",
          "QuitScene": "0",
          "MemChangeCnt": "1",
          "MemChangeList": {
            "Item": "wmj8xBDgAAShxgedm6GT1iiVPVXnutGQ"
          },
          "LastMemVer": "59d8449447a32e24879478a290fdc4a5",
          "CurMemVer": "f7689b09c36d1d7834450aeb2433c5ac"
        }
      }
    ]
  }
}

data 字段说明

键	类型	说明
total	Number	符合条件的记录总条数（用于计算总页数）
pageNum	Number	当前页码
pageSize	Number	每页条数
list	Array	回调记录列表，按落库时间、记录 ID 倒序（最新在前）

list[] 字段说明

字段	类型	说明
id	Number	记录主键
addtime	Number	记录落库时间（unix 时间戳，秒级）
addtime_str	String	落库时间的可读格式 `YYYY-MM-DD HH:mm:ss`
event	String	事件类型，取自报文 `Event`
changetype	String	变更类型，取自报文 `ChangeType`；报文无该字段时为空字符串
detail	String	变更详情，取自报文 `UpdateDetail`；报文无该字段时为空字符串
userid	String	关联的员工 userid；部分事件无值，此时为空字符串
external_userid	String	关联的外部联系人 external_userid；部分事件无值，此时为空字符串
data	Object	解析后的企业微信原始报文体，字段含义见下方附录；解析失败时回落为原始字符串

失败响应

契约下 code 恒为 0，失败通过非空 msg 与空 data 标识。

{ "code": 0, "msg": "starttime格式错误：abc", "data": [] }

错误文案	说明
`starttime格式错误：xxx`	`starttime` 无法解析为时间戳或日期字符串
`endtime格式错误：xxx`	`endtime` 无法解析为时间戳或日期字符串

附录：报文字段说明（企业微信官方口径）

data 为企业微信推送的原始回调报文，字段含义以企微官方文档「接收事件服务器」为准。以下列出公共字段与「客户群变更事件」专有字段。

公共字段（所有事件回调都有）

字段	类型	说明
ToUserName	String	企业 CorpID（企业 ID）
FromUserName	String	此事件固定为 `sys`，表示该消息由系统生成
CreateTime	String	消息创建时间（unix 时间戳，秒级）
MsgType	String	消息类型，事件回调固定为 `event`
Event	String	事件类型，如 `change_external_chat`（客户群变更）、`change_external_contact`（外部联系人变更）

客户群变更事件（`Event` 为 `change_external_chat`）专有字段

字段	类型	说明
ChatId	String	群 ID（客户群唯一标识）
ChangeType	String	变更类型：`create` 群创建、`update` 群变更、`dismiss` 群解散
UpdateDetail	String	变更详情（仅 `ChangeType=update` 时有值）：`add_member` 成员入群、`del_member` 成员退群、`change_owner` 群主变更、`change_name` 群名变更、`change_notice` 群公告变更
JoinScene	String	成员入群时有值，表示入群方式：`0` 由成员邀请入群（含直接邀请和通过邀请链接）、`3` 通过扫描群二维码入群
QuitScene	String	成员退群时有值，表示退群方式：`0` 自己退群、`1` 群主/群管理员移出
MemChangeCnt	String	成员入群或退群时有值，表示本次变更的成员数量
MemChangeList	Object	成员入群或退群时有值，变更的成员列表。`Item` 为变更成员的 external_userid / userid
LastMemVer	String	成员入群或退群时有值，变更前的群成员版本号
CurMemVer	String	成员入群或退群时有值，变更后的群成员版本号

信息

LastMemVer / CurMemVer 是企微用于群成员版本一致性校验的令牌：回调可能乱序或重复到达，业务侧可用版本号判断是否为最新一次变更，避免用旧回调覆盖新状态。

注意事项

MemChangeList.Item 类型不定：只有 1 个变更成员时 Item 为字符串；多个成员时为字符串数组（企业微信 XML 转 JSON 的固有形态），解析时两种形态都要兼容。
其他事件报文字段不同：如 change_external_contact（外部联系人变更）的报文含 UserID、ExternalUserID、State、WelcomeCode 等字段，本接口原样解析返回，字段含义以对应企微官方事件文档为准。
userid / external_userid 并非所有事件都有值：能否取到取决于事件类型，取不到时为空字符串；如报文体里有对应值，可直接解析该条 data 获取。
时间筛选为闭区间：starttime、endtime 均含边界；endtime 仅写到日期时自动补到当天 23:59:59。

变更记录

日期	变更
2026-11-09	首次发布：`/api/getQiyeCallbackMsgList`（GET/POST，筛选参数全部可选），查询企业微信推送到平台的事件回调报文记录；返回落库的事件类型、变更类型、变更详情、员工/外部联系人标识与解析后的原始报文体，支持落库时间区间（闭区间）与 `event` / `changetype` / `detail` 精确筛选，按落库时间倒序分页输出

核心语义​

请求参数​

CURL​

V1（GET）​

V1（POST）​

V2（appid 为 V2 版本）​

成功响应​

data 字段说明​

list[] 字段说明​

失败响应​

附录：报文字段说明（企业微信官方口径）​

公共字段（所有事件回调都有）​

客户群变更事件（Event 为 change_external_chat）专有字段​

注意事项​

相关接口​

变更记录​