--- uuid: "db158436-9638-4c28-a107-89eb3b9e3ddd" type: "tutorial" title: "Webhook 接入说明" sidebar_position: 2 description: "草料 Webhook 可将表单数据以 JSON 格式 POST 到你指定的接口地址，支持新提交、修改、审核结果、标记处理进度四种事件。含前置条件、配置步骤、各事件数据格式及失败重试规则。" keywords: - 草料Webhook - 草料二维码表单数据推送 - Webhook接入 - JSON数据推送 - 表单数据对接 cl_old_blog_id: "65847" cl_old_blog_url: "https://cli.im/help/65847" last_update: date: "2026-04-22" --- 本文介绍如何使用 Webhook 把草料的表单数据推送到你指定的 URL，适用于做消息提醒、数据汇总或对接自有业务系统。 ## 功能介绍 草料把【动态数据】以 JSON 格式 POST 到你指定的接口地址。你的服务需要做到两点： - 允许公网访问 - 在 5 秒内返回 HTTP 200 状态码 如果应答异常，草料会自动重试，最多 5 次，间隔为 15s / 1min / 4min / 16min / 1h。 目前 Webhook **只支持表单数据推送**，包含：新提交、修改、审核结果、标记处理进度。 ## 应用场景 ### 1. 连接第三方应用，实现群消息推送和表格汇总 通过腾讯轻联（腾讯云推出的「应用连接器」），把草料二维码和其他应用连起来，实现群消息推送、数据二次分析、CRM 对接、AI 处理等。[了解详情](/help/integration-and-connection/third-party-integration/tencent-hiflow/connection) ### 2. 对接自有系统 在草料上完成扫码采集，再通过 Webhook 把数据推送到企业自有系统的流程里，保留原系统的同时低成本接入草料的采集能力。 ![Webhook 对接示意](https://blogcdnimg.clewm.net/2022/02/image-1644546273607_16445462739484.png) ## 前置条件 开始配置前请确认： - 你有一个允许公网访问的服务 URL，可接收 POST 请求 - 该服务能在 5 秒内返回 HTTP 200 - 如服务器有防火墙，已将草料出口 IP 加入白名单（见本文「[常见问题 3](#3-部署了防火墙策略如何配置-ip-白名单)」） > **提示**：不同版本每月可推送的动态数据条数不同，免费版 / 基础版 / 高级版为 1000 条/月，旗舰版为 20,000 条/月，行业专属版不限条数。详见 [版本推送说明](/help/purchase-guide/paid-features/api-data-api)。 ## 操作步骤 配置 Webhook 有两种入口：表单设置页（只作用于某个表单）或数据 API 功能页（可统一管理多个表单）。 ### 一、在表单设置页添加 进入表单设置页 → 点击左侧【数据 API】→ 点击【新增数据 API】→ 填写名称和推送 URL → 保存。 > **注**：此设置为表单全局设置，**关联此表单的所有码**都会生效。 ![表单设置页数据 API 入口](https://blogcdnimg.clewm.net/2022/11/image-1668743694361_16687436948264.png) ![表单设置页 Webhook 配置弹窗](https://blogcdnimg.clewm.net/2022/11/image-1668743709153_16687437095751.png) ### 二、在数据 API 功能页添加 进入后台【数据管理】→【数据 API】→【开通 Webhook】→ 填写推送 URL，选择需要推送的表单。已开通时，点击【配置】可以继续添加。 > **注**：如果你用腾讯轻联接 Webhook，由于腾讯轻联无法在中间选择表单，这里只能选一个表单，或直接到该表单设置页中配置。 ![数据 API 功能页](https://blogcdnimg.clewm.net/2024/04/image-1714370711612_17143707125963.png) ![选择推送表单](https://blogcdnimg.clewm.net/2022/11/image-1668743728364_16687437287845.png) ### 三、验证是否配置成功 配置完成后，在关联的表单上提交一条新记录，观察你的服务端： - **收到 POST 请求** → 配置成功，检查 JSON 内容是否符合下文格式 - **未收到请求** → 检查 URL 是否公网可达、防火墙是否放行草料 IP - **收到但内容异常** → 对照下文「字段说明」排查字段映射 ## 推送数据类型 目前仅支持表单记录的数据推送。当二维码是批量子码时，除表单记录外还会一并推送模板名称和可变内容。暂不支持「仅推送子码可变内容」。 - **普通活码**：推送表单记录 - **批量子码**：推送表单记录 + 批量模板名称 + 子码可变内容 ## 推送事件类型 目前支持以下事件： - 新提交表单数据 - 修改表单数据 - 表单审核结果 - 标记处理进度 ## 推送格式 - **请求方式**：POST - **Content-Type**：application/json 草料的所有事件都遵循以下结构： ```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 | ### 示例：有新的表单数据提交 > **注**：表单事件暂不推送音频、视频、文件类型的数据。 ```json { "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` 获取审核结果。 ## 表单组件数据示例 姓名、手机、微信名、身份证号、工号、车牌、性别、单行文本、多行文本、日期、时间、单选项、多级选择、编号等组件都以字符串格式推送： ```json { "fields": { "姓名": "草料", "性别": "男", "多级选择": "浙江省/宁波市/海曙区" } } ``` ### 检查项 检查项以 map 形式推送： ```json { "fields": { "检查项A": "是", "检查项B": "否", "检查项C": "无需填写", "检查项D": "" } } ``` 取值含义： | 值 | 含义 | |------|------| | 是 | √ | | 否 | × | | 无需填写 | / | | 空字符串 | 未填写 | ### 图片 图片类型组件的值是一个对象： ```json { "fields": { "图片": { "preview_url": "https://草料预览URL/", "urls": [ "图片1下载链接", "图片2下载链接" ] } } } ``` ## 常见问题 ### 1. Webhook 功能收费吗？ 草料不同版本对应不同的每月推送动态数据条数： - **免费版、基础版、高级版**：1000 条/月 - **旗舰版**：20,000 条/月 - **行业专属版**：不限条数 详见 [版本推送说明](/help/purchase-guide/paid-features/api-data-api)。 如果通过腾讯轻联对接，腾讯轻联有自己的计费规则（免费版 500 任务/月），详见 [腾讯轻联定价](https://qinglian.tencent.com/price/)。 ### 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`：图片预览页地址，打开后可浏览多张图片，适合以超链接形式展示