Webhook
Webhook 在答卷新增或修改时，把所选数据发送到业务系统的 HTTP 接口。适合报名信息同步、工单创建和业务状态更新。
本文截图来自当前 Chrome 中的“培训报名与反馈（文档演示）”。示例地址使用 example.com 占位，演示任务保持关闭；实际接入时应替换为自己的接收地址。
进入自动推送
打开项目，进入 设置 → 消息通知 → 自动推送。首次配置点击 点击新增；已有任务时点击 新增消息推送任务。
每条任务可以独立开启、关闭、编辑或复制。新建任务保存后默认开启；如果还未准备好接收接口，保存后先将任务关闭。项目设置显示“已自动保存”后生效。
1. 设置触发条件
填写任务名称，例如“报名信息同步”，再选择触发事件和数据范围。
| 配置 | 含义 |
|---|---|
| 新增数据 | 答卷第一次正式提交时触发，包含暂存后的首次提交；填写人和管理员操作均适用 |
| 修改数据 | 已正式提交的答卷被修改时触发；与第一次提交分开配置 |
| 全部数据 | 对符合触发事件的所有答卷执行 |
| 符合条件的数据 | 仅对满足所设条件的答卷执行，例如所属部门为“产品中心” |
只保存草稿不等于正式提交。编辑了任务配置也不会自动补推历史答卷。
2. 配置请求和数据字段
在 操作类型 选择 发送 Webhook。
| 字段 | 配置方法 |
|---|---|
| 请求地址 | 接收方提供的完整接口地址，例如 https://api.example.com/training/registrations |
| 请求方法 | 支持 POST、PUT、PATCH、GET、DELETE；默认 POST。通常使用接收方支持的 POST JSON 接口 |
| 数据字段 | 勾选要放入 answer 的题目答案或系统字段，如姓名、联系邮箱、所属部门、提交时间、答案 ID |
| 认证方式 | 按接收方要求选择无认证、Bearer Token、Basic Auth 或 API Key |
| 请求头 | 默认使用 Content-Type: application/json，可以展开后补充自定义 Header |
接收地址由卷王后端服务器访问。浏览器能打开某个地址，并不一定代表服务器能够访问它。
认证怎么填
| 认证方式 | 需要填写 | 发送方式 |
|---|---|---|
| 无认证 | 无 | 不附加认证信息 |
| Bearer Token | Token | Authorization: Bearer … |
| Basic Auth | 用户名、密码 | HTTP Basic 认证 |
| API Key | Header 名称和 Key | 把 Key 放入指定请求头，例如 X-API-Key |
使用接收系统专门分配的凭证，不要填卷王管理员的登录密码。截图和对外示例中使用占位值。
3. 设置超时、重试和附加参数
展开 高级设置，按业务需要调整。
| 配置 | 当前范围与说明 |
|---|---|
| 超时时间 | 默认 5000 毫秒，可设置 1000 ～ 60000 毫秒 |
| 自定义参数 | 在请求体顶层追加字段；可以填写固定内容，也可以通过“插入问题答案”引用答案 |
| 启用重试 | 默认未开启，按需勾选 |
| 重试次数 | 可填 1 ～ 10；当前实现表示总尝试次数，包含第一次请求。填 3 表示最多发起 3 次请求 |
| 重试间隔 | 默认 1000 毫秒，可设置 100 ～ 10000 毫秒 |
例如增加 source 参数，值填写 training-demo，接收方就可以识别这批数据的来源。不要使用 project、answer、survey 作为自定义参数名，以免覆盖请求体中的同名字段。
接收接口返回 2xx 状态码时视为请求成功。连接失败、超时或非 2xx 响应会按已配置的重试规则处理。业务系统应自行识别重复请求，例如使用“项目 ID + 答案 ID”作为去重依据，避免重复创建记录。
4. 查看推送内容预览
展开 推送内容预览，核对选中的字段、题目 ID 和问卷结构。
预览里的 {{姓名}}、{{createTime}} 等是占位提示，不是实际答卷值，也不代表已经发送成功。
| 顶层字段 | 含义 |
|---|---|
project | 当前项目 ID |
answer | 仅包含所选的题目答案和系统字段；题目使用题目 ID 作为键 |
survey | 当前问卷结构，用于把题目、选项 ID 对应到标题；它不随“数据字段”的勾选而裁剪 |
| 自定义参数 | 追加在顶层，例如 source |
下面是简化的请求体示例，survey 只保留了理解数据所需的部分；实际推送包含完整问卷结构。
{
"project": "demo-project",
"answer": {
"q_name": { "name_input": "示例用户" },
"q_email": { "email_input": "learner@example.com" },
"q_department": { "product_center": true },
"answerId": "demo-answer-001",
"createTime": 1792339200000
},
"survey": {
"id": "demo-project",
"title": "培训报名与反馈",
"children": [
{
"id": "q_department",
"type": "Radio",
"title": "所属部门",
"children": [
{ "id": "product_center", "title": "产品中心", "type": "Option" }
]
}
]
},
"source": "training-demo"
}
单选、多选等题目通常以选项 ID 为键，文本题以填空项 ID 为键；矩阵题还包含行、列层级。不要把所有答案都当成字符串，也不要直接用题目显示标题取值，应结合 survey 结构解析。
系统字段只在勾选后进入 answer。例如选择“答案 ID”后发送 answerId；选择提交时间后发送 createTime。匿名答卷的提交人不会作为普通实名用户信息推送。
5. 联调和查看执行结果
- 用接收系统的测试地址和测试凭证配置任务。
- 核对字段与触发条件后开启任务，提交一份示例答卷。
- 在 统计 → 消息推送 查看本次执行的状态、任务详情、HTTP 状态码或错误信息；也可以从对应答卷的数据详情查看自动化执行情况。
- 对照接收端日志检查数据格式，再决定是否启用重试或条件筛选。
- 失败任务可在执行记录中按页面提供的操作重试。重试前先确认接收方是否已经处理过请求，避免业务重复。
消息通知 → 发送记录用于查看主动发送消息的记录；Webhook 的任务执行应在“统计 → 消息推送”的执行记录中核对。配置页的 JSON 预览不能代替实际联调。
截图中的演示任务保持关闭，因此没有执行记录；实际联调后应以记录详情和接收端日志为准。
常见问题
| 现象 | 检查方法 |
|---|---|
| 提交后没有收到请求 | 检查任务是否开启、答卷是否正式提交、触发事件是否正确、是否满足数据条件 |
| 新增能推送，修改不推送 | 新建或调整一条“修改数据”任务，并核对修改后的数据是否满足条件 |
| 401 或 403 | 检查认证方式、Token、用户名密码或 API Key Header 名称 |
| 404 或连接失败 | 检查后端服务器能否访问目标地址、接口路径和请求方法是否正确 |
| 请求成功但业务没处理 | 2xx 只代表 HTTP 层成功，还需检查接收端业务响应和处理日志 |
| 收到重复数据 | 检查自动重试、手动重试及答卷修改事件；接收端按业务键去重 |
| 答案只有 ID，没有题目名称 | 通过 survey.children 中的题目和选项定义建立映射 |