Skip to main content
Version: latest

Webhook 答卷数据推送

重要提示

该功能为 商业版 付费功能,如未升级,请先 升级 后再使用

监听某个问卷下的答卷事件。 开启了 Webhook 推送的问卷,在特定事件发生时,会以 POST 方法向指定的一个或多个 URL 发送 HTTP 请求,同时带上请求头为 application/json 类型的 JSON 格式数据。

目前支持的事件:

action说明
answer.create用户提交答卷
answer.update用户/管理员修改答卷
answer.delete管理员删除答卷

若有支持其他类型事件的需求,请联系我们。

配置步骤#

  1. 进入问卷编辑页面,点击左上角“设置”,在“回收设置”一栏找到“Webhook”,点击右侧的“设置”,打开 Webhook 设置页;

  2. 点击“新建 Webhook”,根据提示填写配置项,“URL”为请求的目标地址,需要为公网可访问的 HTTP/HTTPS 服务地址。后续会增加可选的密钥项目用于校验。(目标地址不能含有 xip.io,@,端口号且不能是内网地址)

  3. 勾选【启用推送】,点击【确定】按钮,即完成配置。此时问卷服务器将会主动推送一个测试请求,供检查使用。

数据格式字典#

答卷数据#

通用格式说明#

{    "id": "33cc555f-056f-4242-a97c-46f3e7d2016f", // uuid    "object": "Answer", // 对象    "action": "answer.create", // 事件    "created_at": "2021-01-26 14:00:00", // 推送时间    "payload": {        // 问卷编号        "survey_id": 5356056,
        // 回答编号        "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": [          // 每个问卷的结构不一样,结构也会有所出入,实际数据结构以实际推送的为准        ]    }}
参数说明
iduuid
object对象
action行动
created_at推送时间
payload具体内容
payload.survey_id问卷ID
payload.answer_id答卷ID
payload.qq用户在腾讯问卷的标识(非QQ号)
payload.openid非微信OpenID,废弃字段
payload.weixin_openid用户在腾讯问卷的微信 OpenID (默认为空)
payload.started_at用户开始回答的时间
payload.ended_at用户提交答卷的时间
payload.answer用户的回答详情(含有自定义参数
payload.score用户回答的分数(仅旧版测评题有值,新版考试问卷请使用获取考试成绩接口
payload.third_party_user第三方用户信息(特定使用,关联第三方系统对接
signature用于校验的签名(暂不提供)

payload.answer 说明#

[    {        "id": "p-1-ib8x", // 第一页        "questions": [            {                "id": "q-1-IFMp", // 题目ID                "type": "radio",  // 题目类型 - 单选题                "options": [                    {                        "id": "o-100-ABCD", // 回答ID                        "checked": 1,       // 选中                        "text": "<p>选项</p>\n" // 回答内容                    }                ]            },            {                "id": "q-2-EcPa",                "type": "select", // 题目类型 - 下拉题                "options": [                    {                        "id": "o-101-EFGH",                        "checked": 1,                        "text": "选项"                    }                ]            },            {                "id": "q-3-9K6v",                "type": "checkbox", // 题目类型 - 多选题                "options": [                    {                        "id": "o-100-ABCD",                        "checked": 1,                        "text": "<p>选项</p>\n"                    }                ]            },            {                "id": "q-4-Ksi9",                "type": "text", // 题目类型 - 单行文本                "text": "123"            },            {                "id": "q-5-k7p1",                "type": "textarea",  // 题目类型 - 多行文本                "text": "123123\n123123"            },            {                "id": "q-6-pZzn",                "type": "star", // 题目类型 - 量表题                "text": "5"            },            {                "id": "q-7-JNkO",                "type": "matrix_radio", // 题目类型 - 矩阵单选                "groups": [                    {                        "id": "g-1-ABCD",                        "options": [                            {                                "id": "o-101-EFGH",                                "checked": 1,                                "text": "<p>选项</p>\n"                            }                        ]                    },                    {                        "id": "g-2-EFGH",                        "options": [                            {                                "id": "o-101-EFGH",                                "checked": 1,                                "text": "<p>选项</p>\n"                            }                        ]                    }                ]            },            {                "id": "q-8-a5nI",                "type": "matrix_checkbox", // 题目类型 - 矩阵多选                "groups": [                    {                        "id": "g-1-ABCD",                        "options": [                            {                                "id": "o-100-ABCD",                                "checked": 1,                                "text": "<p>选项</p>\n"                            },                            {                                "id": "o-101-EFGH",                                "checked": 1,                                "text": "<p>选项</p>\n"                            }                        ]                    },                    {                        "id": "g-2-EFGH",                        "options": [                            {                                "id": "o-100-ABCD",                                "checked": 1,                                "text": "<p>选项</p>\n"                            },                            {                                "id": "o-101-EFGH",                                "checked": 1,                                "text": "<p>选项</p>\n"                            }                        ]                    }                ]            }        ]    },    {        "id": "p-2-ohuS",        "questions": [            {                "id": "q-9-VDhO",                "type": "matrix_star", // 题目类型 - 矩阵量表                "groups": [                    {                        "id": "g-1-ABCD",                        "text": "5"                    },                    {                        "id": "g-2-EFGH",                        "text": "5"                    }                ]            },            {                "id": "q-10-SZMU",                "type": "sort", // 题目类型 - 排序题                "options": [                    {                        "id": "o-101-EFGH",                        "sort_no": 1                    },                    {                        "id": "o-100-ABCD",                        "sort_no": 2                    }                ]            },            {                "id": "q-11-vtGs",                "type": "chained_selects", // 题目类型 - 联动题                "id_list": [                    "2-AK",                    "3-nV",                    "4-qA"                ],                "text_list": [                    "1",                    "2",                    "3"                ]            },            {                "id": "q-12-MBer",                "type": "upload",  // 题目类型 - 附件题                "expired": "7d",  // 链接有效时间为7天                "url": "", // 弃用,目前支持多附件,请使用 files 字段                "files": [{                  "name": "图片1.png",                  "url": "https://xxx.png"                },{                  "name": "图片2.png",                  "url": "https://yyy.png"                }]            },            {                "id": "q-14-Xlvy",                "type": "text_multiple",  // 题目类型 - 填空题                "blanks": [                    {                        "id": "fillblank-WPph",                        "value": "wj.qq.com"                    }                ]            },
            // 疫情申报问卷,获取上传的健康码及图片识别结果            {              "id": "q-10-Zr6w",              "type": "upload",              "expired": "7d", // 链接有效时间为7天              "files": [{                "name": "核酸检测.png",                "url": "https://zzz.png"              }],            }, {              "id": "q-9-fRX5-ret",              "type": "radio",              "options": [{                "id": "o-102-FEAS",                "text": "异常", // 目前仅返回【正常/异常】                "checked": 1              }]            }        ]    },    {        "id": "custom_args", // 自定义参数        "questions": [            {                "id": "custom-arg-01", // 自定义参数ID                "type": "text", // 类型                "text": "123" // 内容            }        ]    }]

服务端调试示例#

下面以 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 列表接口获取。