Webhook 问卷事件推送格式

重要提示

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

简介

监听某个用户/团队下的问卷事件。 当事件发生时，服务端会以 POST 方法向指定的一个或多个 URL 发送 HTTP 请求，同时带上请求头为 application/json 类型的 JSON 格式数据。

支持的事件：

action	说明
survey.created	用户或团队下新增问卷
survey.updated	问卷内容被修改
survey.deleted	问卷被删除

配置步骤

通过接口对用户或团队进行事件注册，查看接口文档。

数据格式

参数说明

参数	类型	说明
id	string	uuid
object	string	对象类型
action	string	事件类型
created_at	string	推送时间
payload	object	具体内容
payload.object	string	对象类型
payload.id	integer	问卷ID
payload.hash	string	问卷Hash
payload.title	string	问卷标题
payload.owner_user_id	integer	问卷所属用户ID或团队ID
payload.editor_user_id	integer	操作问卷的用户ID
payload.state	integer	问卷状态（2:回收中, 3:暂停回收）
payload.created_at	string	问卷创建时间
payload.updated_at	string	问卷更新时间
payload.trace_id	string	用于第三方追踪问卷

trace_id 补充说明

• 引导用户打开编辑页链接如下：https://wj.qq.com/edit/v2.html?org=60016179293&trace_id=1fd3d87f-b7f9-44fd-af6e-90801620160a
• 用户在该链接下创建的问卷，事件回推时会带上 trace_id

备注：org 为团队 ID，trace_id 为 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12) 格式的随机字符串，可以使用 UUID 相关工具库生成。使用方记录 trace_id 的使用场景，在接收事件时可以用来追溯。

数据示例

{  "id": "33cc555f-056f-4242-a97c-46f3e7d2016f",  "object": "Survey",  "action": "survey.created",  "created_at": "2022-01-26 14:00:00",  "payload": {    "object": "Survey",    "id": 123456,    "hash": "abcd",    "title": "问卷标题",    "owner_user_id": 60000000004,    "editor_user_id": 60000000005,    "created_at": "2022-01-26 14:00:00",    "updated_at": "2022-01-26 14:00:00",    "trace_id": "1fd3d87f-b7f9-44fd-af6e-90801620160a"  }}

服务端调试示例

下面以 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 内容是否接收到相关测试请求数据

重试机制

服务端接受 Webhook 内容成功后，应在5秒钟内返回 HTTP 状态码 200，否则将视为推送失败。推送失败的 Webhook 事件将会进入重试队列，最多重试 7 次。

重试规则如下：

• 第一次重试，首次失败后 2 分钟
• 第二次重试，首次失败后 10 分钟
• 第三次重试，首次失败后 30 分钟
• 第四次重试，首次失败后 1 小时
• 第五次重试，首次失败后 2 小时
• 第六次重试，首次失败后 6 小时
• 第七次重试，首次失败后 15 小时

安全

检测 Webhook 请求是否来自腾讯问卷

Webhook 请求时将从一批 IP 地址发起请求，接收端可用于校验请求是否可信。请通过 IP 列表接口获取。