WebHook推送数据

TDuckX WebHook 数据推送

TDuckX 支持通过 WebHook 将表单数据实时推送到外部系统。当表单数据发生变化时，系统会自动向指定地址发送 HTTP 请求，实现 系统集成、数据同步和自动化处理。

WebHook 常用于：

  • 表单数据同步到 CRM / ERP / OA 系统
  • 自动触发业务流程
  • 与企业内部系统进行数据集成

每个表单均可独立配置 WebHook 推送。

配置位置

进入表单管理页面：

表单发布 → 数据推送 → WebHook配置

配置完成后，当表单数据发生变化时，系统会自动向配置地址推送数据。

配置示例：

图片

请求方式

WebHook 支持两种 HTTP 请求方式：

请求方式 说明
POST 推荐方式，请求体为 JSON
GET 通过 URL 参数传递数据

推荐使用 POST + JSON 方式，便于解析复杂数据结构。

事件类型

WebHook 支持监听三种数据事件：

事件类型 eventType 说明
新增 form_data_add 用户提交表单
修改 form_data_update 数据被修改
删除 form_data_delete 数据被删除

开发者可以根据业务需求选择监听的事件。

推送流程

WebHook 推送流程如下：

用户提交表单
      ↓
TDuckX保存数据
      ↓
触发WebHook事件
      ↓
向配置地址发送HTTP请求
      ↓
外部系统接收并处理数据

推送日志

系统提供 WebHook推送日志，用于查看推送状态。

日志内容包括：

  • 推送时间
  • 推送数据
  • 请求结果
  • 返回状态

示例：

图片

请求格式

POST 请求

POST /webhook HTTP/1.1
Content-Type: application/json

请求体：

{
  "dataId": "b0b880fed17c4220bc227adbc6b191b5",
  "formKey": "SuKtWkZB",
  "serialNumber": 4,
  "eventType": "form_data_add",
  "eventTime": 1773651391542,
  "createTime": "2026-03-16 16:56:31",
  "updateTime": "2026-03-16 16:56:31"
}

GET 请求

如果使用 GET 方式，数据将以 URL 参数形式传递：

https://example.com/webhook?dataId=xxx&formKey=xxx&eventType=form_data_add

完整数据结构

示例数据：

{
  "input1773629696276": "2310732603@qq.com",
  "input1773629698446": "webhook测试",
  "totalScore": 0,
  "sumTotalScore": 1,
  "dataId": "b0b880fed17c4220bc227adbc6b191b5",
  "formKey": "SuKtWkZB",
  "serialNumber": 4,
  "submitUa": {
    "browser": {
      "name": "Chrome",
      "version": "146.0.0.0"
    },
    "os": {
      "name": "Mac OS",
      "version": "10.15.7"
    }
  },
  "submitOs": "Mac OS",
  "submitBrowser": "Chrome",
  "submitRequestIp": "113.220.118.81",
  "submitAddress": "湖南省-邵阳市",
  "completeTime": 13091,
  "userId": 1,
  "createByName": "超级管理员",
  "beginTime": "2026-03-16 16:56:18",
  "createTime": "2026-03-16 16:56:31",
  "updateTime": "2026-03-16 16:56:31",
  "eventType": "form_data_add",
  "eventTime": 1773651391542
}

字段说明

字段 类型 说明
formKey string 表单唯一标识
dataId string 表单数据ID
serialNumber number 数据序号
eventType string 事件类型
eventTime number 事件时间戳
createTime datetime 创建时间
updateTime datetime 更新时间
submitRequestIp string 提交IP
submitAddress string 提交地址
submitBrowser string 浏览器
submitOs string 操作系统
totalScore number 当前得分
sumTotalScore number 总分

动态字段：

字段 说明
inputxxxx 表单字段值，对应组件ID

返回规范（建议）

外部系统收到 WebHook 后，建议返回以下格式：

成功：

{
  "code": 0,
  "message": "success"
}

HTTP状态码：

状态码 说明
200 接收成功
400 请求错误
500 服务器错误

如果返回非 200 状态码，TDuckX 将记录推送失败日志。

接收示例

Java 示例

@PostMapping("/webhook")
public String webhook(@RequestBody Map<String,Object> data){
    System.out.println("接收到数据："+data);
    return "success";
}

Node.js 示例

app.post('/webhook', (req, res) => {
  console.log(req.body)
  res.json({code:0,message:"success"})
})

PHP 示例

$data = json_decode(file_get_contents("php://input"), true);
file_put_contents("log.txt", json_encode($data));
echo json_encode(["code"=>0,"message"=>"success"]);

安全建议

为了保证 WebHook 的安全性，建议：

1️⃣ 使用 HTTPS 接口地址 2️⃣ 增加 Token 校验 3️⃣ 对 IP 进行白名单限制 4️⃣ 记录接收日志