Webhook 答卷数据推送
监听某个问卷下的答卷事件。 开启了 Webhook 推送的问卷，在特定事件发生时，会以 POST 方法向指定的一个或多个 URL 发送 HTTP 请求，同时带上请求头为 application/json 类型的 JSON 格式数据。
目前支持的事件：
| action | 说明 |
|---|---|
| answer.create | 用户提交答卷 |
| answer.update | 用户/管理员修改答卷 |
| answer.delete | 管理员删除答卷 |
若有支持其他类型事件的需求，请联系我们。
配置步骤
进入问卷编辑页面，点击左上角“设置”，在“回收设置”一栏找到“Webhook”，点击右侧的“设置”，打开 Webhook 设置页；
点击“新建 Webhook”，根据提示填写配置项，“URL”为请求的目标地址，需要为公网可访问的 HTTP/HTTPS 服务地址。后续会增加可选的密钥项目用于校验。(目标地址不能含有
xip.io,@,端口号且不能是内网地址)勾选【启用推送】，点击【确定】按钮，即完成配置。此时问卷服务器将会主动推送一个测试请求，供检查使用。
数据格式字典
答卷数据
通用格式说明
{
"id": "33cc555f-056f-4242-a97c-46f3e7d2016f", // uuid
"object": "Answer", // 对象
"action": "answer.create", // 事件
"created_at": "2021-01-26 14:00:00", // 推送时间
"payload": {
// 问卷编号
"survey_id": 5356056,
// 问卷hash
"survey_hash": "abc1",
// 回答编号
"answer_id": 7,
// 问卷系统中回答者身份ID，非真实 QQ 号
"respondent_id": 60000000001,
// 回答者登录类型（微信/QQ/企业微信/手机等）
"respondent_type": "",
// 自定义字段 （非微信OpenID，废弃字段）
"openid": "",
// 用户开始答卷的时间
"started_at": "2020-02-09 11:55:30",
// 用户提交答卷的时间
"ended_at": "2020-02-09 11:58:39",
// 回答时长（秒）
"duration": 189,
// 地理位置信息
"country": "中国", // 国家或地区
"province": "广东省", // 省份
"city": "深圳市", // 城市
// 客户端信息
"ip": "127.0.0.1", // 答题 IP 地址
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 15_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148", // 浏览器信息
"referrer": "https://wj.qq.com/xxx.html", // 进入答题页的来源地址
// 第三方用户信息（仅第三方对接场景下使用，参考 https://wj.qq.com/docs/openapi/sso/create_user 使用）
"third_party_user": {
"respondent_id": 60000000001, // 问卷系统中回答者身份ID，接口注册用户时由问卷系统自动生成
"openid": "abcdefg", // 第三方用户标识，接口注册用户时由使用方传入
"nickname": "张三" // 第三方用户昵称，接口注册用户时由使用方传入
},
// 用户的回答详情
"answer": [
// 每个问卷的结构不一样，结构也会有所出入，实际数据结构以实际推送的为准
]
}
}
| 参数 | 说明 |
|---|---|
| id | uuid |
| object | 对象 |
| action | 行动 |
| created_at | 推送时间 |
| payload | 具体内容 |
| payload.survey_id | 问卷ID |
| payload.answer_id | 答卷ID |
| payload.qq | 用户在腾讯问卷的标识（非QQ号） |
| payload.openid | 非微信OpenID，废弃字段 |
| payload.weixin_openid | 用户在腾讯问卷的微信 OpenID （默认为空） |
| payload.weixin_tp_openid | 用户在授权公众号的微信 OpenID （默认为空） |
| payload.started_at | 用户开始回答的时间 |
| payload.ended_at | 用户提交答卷的时间 |
| payload.answer | 用户的回答详情（含有自定义参数） |
| payload.score | 用户回答的分数（仅旧版测评题有值，新版考试问卷请使用获取考试成绩接口） |
| payload.third_party_user | 第三方用户信息（特定使用，关联第三方系统对接） |
| signature | 用于校验的签名（暂不提供） |
payload.answer 说明
[
{
"id": "p-1-abcd",
"questions": [
{
"id": "q-1-abcd", // 题目ID
"type": "radio", // 题目类型-单选题
"options": [
{
"id": "o-100-ABCD", // 选项ID
"checked": 1, // 选中
"text": "选项" // 选项内容
}
],
"blanks": []
},
{
"id": "q-2-tJQP", // 题目ID
"type": "checkbox", // 题目类型-多选题
"options": [
{
"id": "o-0-ewtp", // 选项ID
"checked": 1, // 选中
"text": "选项" // 选项内容
},
{
"id": "o-1-es3e",
"checked": 1,
"text": "选项"
}
],
"blanks": []
},
{
"id": "q-3-fRq4", // 题目ID
"type": "select", // 题目类型-下拉题
"options": [
{
"id": "o-0-KSha",
"checked": 1,
"text": "选项"
}
]
},
{
"id": "q-4-kyUN",
"type": "image_radio", // 题目类型-图片单选题
"options": [
{
"id": "o-0-zY8L",
"checked": 1,
"text": "选项"
}
]
},
{
"id": "q-5-JonQ",
"type": "image_checkbox", // 题目类型-图片多选题
"options": [
{
"id": "o-0-jLV0",
"checked": 1,
"text": "选项"
},
{
"id": "o-1-VIsn",
"checked": 1,
"text": "选项"
}
]
},
{
"id": "q-6-wd0W",
"type": "text", // 题目类型-单行文本题
"text": "测试文本" // 文本内容
},
{
"id": "q-7-sGeQ", // 题目ID
"type": "blanks", // 题目类型-填空题
"blanks": [
{
"id": "fillblank-f5a0", // 填空ID
"value": "测试" // 填空内容
},
{
"id": "fillblank-fee6",
"value": "cat"
},
{
"id": "fillblank-519a",
"value": "apple"
}
]
},
{
"id": "q-8-Qu2R", // 题目ID
"type": "textarea", // 题目类型-多行文本题
"text": "测试多行文本" // 文本内容
},
{
"id": "q-9-iFUk", // 题目ID
"type": "star", // 题目类型-量表题
"text": "7" // 量表分值
},
{
"id": "q-10-wrrV", // 题目ID
"type": "nps", // 题目类型-NPS题
"text": "9" // NPS分值
},
{
"id": "q-11-aTdU", // 题目ID
"type": "star", // 题目类型-评价打分题
"text": "4" // 分值
},
{
"id": "q-12-CBZu", // 题目ID
"type": "sort", // 题目类型-排序题
"options": [
{
"id": "o-0-se03", // 选项ID
"sort_no": 1 // 排序顺序
},
{
"id": "o-1-Fcs1",
"sort_no": 2
}
],
"blanks": []
},
{
"id": "q-13-9OV2", // 题目ID
"type": "upload", // 题目类型-图片附件题
"files": [
{
"name": "logo.png",
"url": "https://wj.qq.com/api/files/show?file_id=123&survey_id=292192&question_id=q-11-3rG8&file_name=292192_0_6603fef4e5abd7616bfef24eb516aaef.png"
},
{
"name": "logo2.png",
"url": "https://wj.qq.com/api/files/show?file_id=124&survey_id=292192&question_id=q-11-3rG8&file_name=292192_0_6603fef4e5abd7616bfef24eb516aaeh.png"
}
],
},
{
"id": "q-14-HF17", // 题目ID
"type": "chained_selects", // 题目类型-多级联动题
"id_list": [
"l-abc1",
"l-ab11"
],
"text_list": [
"选项1",
"子选项1"
]
},
{
"id": "q-15-pZ0A", // 题目ID
"type": "datetime", // 题目类型-时间日期题
"text": "2025-10-17T00:00:00.000+08:00"
},
{
"id": "q-16-9H9z", // 题目ID
"type": "signature", // 题目类型-签名题
"text": "",
"signature_id": "Ark9b4QVjP" // 签名ID
},
{
"id": "q-17-hI2O", // 题目ID
"type": "address", // 题目类型-地理位置题
"text": "广东省深圳市南山区深南大道10000号", // 地理位置
"address_detail": "",
"address_label": "腾讯大厦", // 地址名称
"lat": 22.540366, // 纬度
"lng": 113.934559 // 经度
},
{
"id": "q-18-0xXv", // 题目ID
"type": "max_diff", // 题目类型-MaxDiff
"max_diff": [
[
{
"id": "o-0-rlE5",
"value": -1
},
{
"id": "o-2-baFG",
"value": 0
},
{
"id": "o-1-4WcV",
"value": 1
}
],
[
{
"id": "o-3-7QND",
"value": 0
},
{
"id": "o-1-4WcV",
"value": 1
},
{
"id": "o-0-rlE5",
"value": -1
}
]
]
},
{
"id": "q-19-9l16", // 题目ID
"type": "matrix_radio", // 题目类型-矩阵单选题
"groups": [
{
"id": "g-1-ABCD",
"options": [
{
"id": "o-1-WAbC",
"checked": 1,
"text": "选项2",
"sort_no": 0
}
]
},
{
"id": "g-2-EFGH",
"options": [
{
"id": "o-0-0WPX",
"checked": 1,
"text": "选项1",
"sort_no": 0
}
]
}
]
},
{
"id": "q-20-h7qr",
"type": "matrix_checkbox", // 题目类型-矩阵多选题
"groups": [
{
"id": "g-1-ABCD",
"options": [
{
"id": "o-0-oFyk",
"checked": 1,
"text": "选项1",
"sort_no": 0
},
{
"id": "o-1-6NNV",
"checked": 1,
"text": "选项2",
"sort_no": 0
}
]
},
{
"id": "g-2-EFGH",
"options": [
{
"id": "o-1-6NNV",
"checked": 1,
"text": "选项2",
"sort_no": 0
}
]
}
]
},
{
"id": "q-21-U6cV",
"type": "matrix_star", // 题目类型-矩阵量表题
"groups": [
{
"id": "g-1-ABCD",
"text": "8",
"answer_tags": []
},
{
"id": "g-2-EFGH",
"text": "3",
"answer_tags": []
}
]
},
{
"id": "q-22-pP4d",
"type": "matrix_star", // 题目类型-矩阵打分题
"groups": [
{
"id": "g-1-ABCD",
"text": "3",
"answer_tags": []
},
{
"id": "g-2-EFGH",
"text": "4",
"answer_tags": []
}
]
},
{
"id": "q-23-mUma",
"type": "matrix_blank", // 题目类型-矩阵填空
"groups": [
{
"id": "g-1-ABCD",
"blanks": [
{
"id": "o-1-abcd",
"text": "填空",
"value": "test1"
},
{
"id": "o-2-efgh",
"text": "带联想填空",
"value": "apple"
},
{
"id": "o-3-SznN",
"text": "下拉",
"value": "cat"
}
]
},
{
"id": "g-2-EFGH",
"blanks": [
{
"id": "o-1-abcd",
"text": "填空",
"value": "test2"
},
{
"id": "o-2-efgh",
"text": "带联想填空",
"value": "cat"
},
{
"id": "o-3-SznN",
"text": "下拉",
"value": "boy"
}
]
}
]
},
{
"id": "q-24-cdWL",
"type": "sheet", // 题目类型-自增表格题
"groups": [
{
"id": "g-0",
"blanks": [
{
"id": "o-1-abcd",
"text": "填空",
"value": "表格填空"
},
{
"id": "o-2-efgh",
"text": "带联想填空",
"value": "联想填空"
},
{
"id": "o-3-SznN",
"text": "下拉",
"value": "boy"
}
]
},
{
"id": "g-1",
"blanks": [
{
"id": "o-1-abcd",
"text": "填空",
"value": "1"
},
{
"id": "o-2-efgh",
"text": "带联想填空",
"value": "2"
},
{
"id": "o-3-SznN",
"text": "下拉",
"value": "apple"
}
]
}
]
},
{
"id": "q-2-KALh",
"type": "phone", // 题目类型-手机号码
"text": "86-135xxxxxxxxx",
"is_verified": true, // 是否已经认证
"title": "请填写手机号",
}
]
},
{
"id": "p-2-bKoP",
"questions": [
{
"id": "q-50-XC8E",
"type": "chained_selects",
"id_list": [
"2-wA",
"3-v9",
"4-1L"
],
"text_list": [
"一级答案",
"二级答案",
"三级答案"
]
},
{
"id": "q-55-3rG8",
"type": "upload",
"file_name_src": "logo.png",
"file_name_dst": "292192_0_6603fef4e5abd7616bfef24eb516aaef.png",
"files": [
{
"name": "logo.png",
"url": "https://wj.qq.com/api/files/show?file_id=123&survey_id=292192&question_id=q-11-3rG8&file_name=292192_0_6603fef4e5abd7616bfef24eb516aaef.png"
},
{
"name": "logo2.png",
"url": "https://wj.qq.com/api/files/show?file_id=124&survey_id=292192&question_id=q-11-3rG8&file_name=292192_0_6603fef4e5abd7616bfef24eb516aaeh.png"
}
],
"expired": "7d"
}
]
}
{
"id": "custom_args", // 自定义参数
"questions": [
{
"id": "custom-arg-01", // 自定义参数ID
"type": "text", // 类型
"text": "123", // 内容
"title": "userid", // 自定义参数 key 值
"description": "用户ID，传递用户身份信息" // 自定义参数描述
}
]
}
]
服务端调试示例
下面以 PHP 开发语言为示例：
<?php
// 接受请求参数
$event = json_decode(file_get_contents("php://input"));
// 写入文件
$myfile = fopen("wj.qq.com.log", "w") or die("Unable to open file!");
fwrite($myfile, json_encode($event));
fclose($myfile);
查看 wj.qq.com.log 内容是否接收到相关测试请求数据，例如下面：
{
"id": "ac3a878b-3ada-4f00-a052-fb60c33414de", // uuid
"object": "webhook", // 对象
"action": "webhook.test", // 行动
"created_at": "2021-01-26 14:49:39", // 推送时间
}
重试机制
服务端接受 Webhook 内容成功后，应在5秒钟内返回 HTTP 状态码 200，否则将视为推送失败。推送失败的 Webhook 事件将会进入重试队列，最多重试 7 次。
重试规则如下：
- 第一次重试，首次失败后 2 分钟
- 第二次重试，首次失败后 10 分钟
- 第三次重试，首次失败后 30 分钟
- 第四次重试，首次失败后 1 小时
- 第五次重试，首次失败后 2 小时
- 第六次重试，首次失败后 6 小时
- 第七次重试，首次失败后 15 小时
安全
检测 Webhook 请求是否来自腾讯问卷
Webhook 请求时将从一批 IP 地址发起请求，接收端可用于校验请求是否可信。请通过 IP 列表接口获取。