跳到主要内容

Webhook 接入说明

本文介绍如何使用 Webhook 把草料的表单数据推送到你指定的 URL，适用于做消息提醒、数据汇总或对接自有业务系统。

功能介绍​

草料把【动态数据】以 JSON 格式 POST 到你指定的接口地址。你的服务需要做到两点：

  • 允许公网访问
  • 在 5 秒内返回 HTTP 200 状态码

如果应答异常，草料会自动重试，最多 5 次，间隔为 15s / 1min / 4min / 16min / 1h。

目前 Webhook 只支持表单数据推送，包含：新提交、修改、审核结果、标记处理进度。

应用场景​

1. 连接第三方应用，实现群消息推送和表格汇总​

通过腾讯轻联（腾讯云推出的「应用连接器」），把草料二维码和其他应用连起来，实现群消息推送、数据二次分析、CRM 对接、AI 处理等。了解详情

2. 对接自有系统​

在草料上完成扫码采集，再通过 Webhook 把数据推送到企业自有系统的流程里，保留原系统的同时低成本接入草料的采集能力。

Webhook 对接示意

前置条件​

开始配置前请确认：

  • 你有一个允许公网访问的服务 URL，可接收 POST 请求
  • 该服务能在 5 秒内返回 HTTP 200
  • 如服务器有防火墙，已将草料出口 IP 加入白名单（见本文「常见问题 3」）

提示：不同版本每月可推送的动态数据条数不同，免费版 / 基础版 / 高级版为 1000 条/月，旗舰版为 20,000 条/月，行业专属版不限条数。详见 版本推送说明。

操作步骤​

配置 Webhook 有两种入口：表单设置页（只作用于某个表单）或数据 API 功能页（可统一管理多个表单）。

一、在表单设置页添加​

进入表单设置页 → 点击左侧【数据 API】→ 点击【新增数据 API】→ 填写名称和推送 URL → 保存。

注：此设置为表单全局设置，关联此表单的所有码都会生效。

表单设置页数据 API 入口

表单设置页 Webhook 配置弹窗

二、在数据 API 功能页添加​

进入后台【数据管理】→【数据 API】→【开通 Webhook】→ 填写推送 URL，选择需要推送的表单。已开通时，点击【配置】可以继续添加。

注：如果你用腾讯轻联接 Webhook，由于腾讯轻联无法在中间选择表单，这里只能选一个表单，或直接到该表单设置页中配置。

数据 API 功能页

选择推送表单

三、验证是否配置成功​

配置完成后，在关联的表单上提交一条新记录，观察你的服务端：

  • 收到 POST 请求 → 配置成功，检查 JSON 内容是否符合下文格式
  • 未收到请求 → 检查 URL 是否公网可达、防火墙是否放行草料 IP
  • 收到但内容异常 → 对照下文「字段说明」排查字段映射

推送数据类型​

目前仅支持表单记录的数据推送。当二维码是批量子码时，除表单记录外还会一并推送模板名称和可变内容。暂不支持「仅推送子码可变内容」。

  • 普通活码：推送表单记录
  • 批量子码：推送表单记录 + 批量模板名称 + 子码可变内容

推送事件类型​

目前支持以下事件：

  • 新提交表单数据
  • 修改表单数据
  • 表单审核结果
  • 标记处理进度

推送格式​

  • 请求方式：POST
  • Content-Type：application/json

草料的所有事件都遵循以下结构：

{
  "time": "2022-06-30 17:06:39",
  "event": "事件标识",
  "data": {}
}
字段含义类型
time事件发生时间，采用东八区 YYYY-mm-dd HH:ii:ss 格式string
event事件标识，枚举见下文string
data事件数据，不同事件格式不同object

事件标识枚举​

事件标识
有新的表单数据提交FORM_DATA_SUBMIT
表单数据被编辑FORM_DATA_EDITED
表单数据被审核FORM_DATA_REVIEW

示例：有新的表单数据提交​

注：表单事件暂不推送音频、视频、文件类型的数据。

{
  "time": "2022-06-30 17:06:39",
  "event": "FORM_DATA_SUBMIT",
  "data": {
    "ref_data": {
      "created_at": "2022-06-30 17:06:39",
      "serial_number": "L1000001",
      "form": {
        "number": "D20",
        "name": "会议签到"
      },
      "submitter": {
        "name": "填写人A",
        "phone_number": "18888881111"
      },
      "review": {
        "state": "待审核",
        "time": "2022-06-30 17:06:39"
      },
      "process": {
        "state": "未处理",
        "time": "2022-06-30 17:06:39"
      },
      "fields": {
        "姓名": "草料",
        "手机": "18888648888",
        "微信名": "CHEN",
        "身份证号": "330200000000000000",
        "工号": "FBI100",
        "单选项": "是",
        "多选项": [
          "选项1",
          "选项3"
        ],
        "检查项": {
          "项目1": "是",
          "项目2": "否",
          "项目3": "无需填写",
          "项目4": ""
        }
      },
      "ref_qrcode": {
        "name": "测试二维码",
        "type": "CHILD",
        "code": "qAbCxZ",
        "template": {
          "name": "测试模板"
        },
        "fields": {
          "文本1填充位": "A",
          "文本2填充位": "B"
        },
        "state": {
          "状态组1": "异常",
          "状态组2": "正常"
        }
      }
    }
  }
}

字段说明​

字段描述类型
time事件发生时间string
event事件标识string
data事件详情数据object
data.ref_data事件中表单详情数据object
data.ref_data.created_at填表时间string
data.ref_data.serial_number记录编号string
data.ref_data.web_url记录地址string
data.ref_data.form表单信息object
data.ref_data.form.number表单编号string
data.ref_data.form.name表单名称string
data.ref_data.submitter表单填写人信息object
data.ref_data.submitter.name填写人姓名string
data.ref_data.submitter.phone_number填写人手机号string
data.ref_data.review审核信息（仅开启审核功能时存在）object
data.ref_data.review.state审核状态：审核中 / 审核通过 / 审核不通过string
data.ref_data.review.time审核时间string
data.ref_data.process闭环信息（仅开启闭环功能时存在）object
data.ref_data.process.state闭环处理状态string
data.ref_data.process.time闭环处理时间string
data.ref_data.fields表单字段（组件）信息map
data.ref_qrcode二维码信息object
data.ref_qrcode.name二维码名称string
data.ref_qrcode.type二维码类型：CHILD（子码）/ NORMAL（普通活码）string
data.ref_qrcode.code码唯一标识string
data.ref_qrcode.web_url码链接string
data.ref_qrcode.template码模板信息（仅子码存在）object
data.ref_qrcode.template.name码模板名称string
data.ref_qrcode.fields子码填充位信息（仅子码存在）object
data.ref_qrcode.state码状态信息map

其中 data.ref_data.fields 和 data.ref_qrcode.fields 都是 key / value 结构。key 代表组件或填充位名称，value 的类型由组件类型决定。

表单数据被编辑​

事件标识：FORM_DATA_EDITED，请求数据与「新提交」事件格式相同。

表单数据被审核​

事件标识：FORM_DATA_REVIEW，请求数据与「新提交」事件格式相同，可通过 data.ref_data.review.state 获取审核结果。

表单组件数据示例​

姓名、手机、微信名、身份证号、工号、车牌、性别、单行文本、多行文本、日期、时间、单选项、多级选择、编号等组件都以字符串格式推送：

{
  "fields": {
    "姓名": "草料",
    "性别": "男",
    "多级选择": "浙江省/宁波市/海曙区"
  }
}

检查项​

检查项以 map 形式推送：

{
  "fields": {
    "检查项A": "是",
    "检查项B": "否",
    "检查项C": "无需填写",
    "检查项D": ""
  }
}

取值含义：

值含义
是√
否×
无需填写/
空字符串未填写

图片​

图片类型组件的值是一个对象：

{
  "fields": {
    "图片": {
      "preview_url": "https://草料预览URL/",
      "urls": [
        "图片1下载链接",
        "图片2下载链接"
      ]
    }
  }
}

常见问题​

1. Webhook 功能收费吗？​

草料不同版本对应不同的每月推送动态数据条数：

  • 免费版、基础版、高级版：1000 条/月
  • 旗舰版：20,000 条/月
  • 行业专属版：不限条数

详见 版本推送说明。

如果通过腾讯轻联对接，腾讯轻联有自己的计费规则（免费版 500 任务/月），详见 腾讯轻联定价。

2. 推送条数是怎么计算的？​

每次数据推送算一条，包括：新表单记录、完成审核、变更闭环状态、修改表单记录。

3. 部署了防火墙策略，如何配置 IP 白名单？​

如果你的服务器部署了防火墙，请将下列草料平台出口 IP 加入白名单：

121.199.48.107
121.199.77.89
121.41.17.80
121.40.50.111
121.199.27.189
114.55.32.66
121.199.9.30
116.62.49.155
121.199.78.132
101.37.77.33
114.55.34.111
121.43.43.35
116.62.108.126
47.99.151.190
47.98.201.29
47.98.163.22
121.40.210.160
121.199.29.82
118.178.186.120
47.98.205.233

4. 图片组件的两个地址怎么选？​

每个图片组件提供两个地址：xxx.urls 和 xxx.preview_url。

  • xxx.urls：图片直链数组，可直接显示图片（多图时不能同时显示），适合群消息推送直显或 AI 识别
  • xxx.preview_url：图片预览页地址，打开后可浏览多张图片，适合以超链接形式展示