Webhooks

回复一到达，就以 JSON 形式发送到您自己的地址。

每条回复一次 POST

回答存好后立即发送，不会让填写者等待。

稳定的 JSON 结构

公开的类型名和永久的字段 ID，重命名问题不会破坏您的代码。

10 秒，仅一次

Fillio 会等待您的端点十秒，之后不再重试。

开启 Webhook

打开表单，进入“设置”标签页并打开 Webhook 开关。粘贴接收提交的地址；您停止输入片刻后 Fillio 会保存它并在界面上确认。每个表单只带一个地址，把开关关掉会清除它。

地址必须是 HTTPS

Fillio 只会调用以 https:// 开头的地址。http:// 地址在设置字段里能被接受，但永远不会被调用，因此一个看似已保存的 webhook 会悄无声息地什么都不发。

指向内网的地址同样会被拒绝：10.x、127.x、169.254.x、172.16-31.x 或 192.168.x 上的任何主机，任何 IPv6 地址，以及名为 localhost 或以 .local、.internal 结尾的任何域名。您的端点必须能从公网访问。

请求

一个带 JSON 主体的 POST。随附四个请求头。

请求头	说明
Content-Type: application/json	主体始终是 JSON。
User-Agent: Fillio Webhooks/1.0	表明调用方是 Fillio，当一个端点同时监听多个服务时很有用。
X-Fillio-Event: FORM_RESPONSE	事件名称。FORM_RESPONSE 是目前 Fillio 唯一会发送的值。
X-Fillio-Event-Id	本次投递的全新 UUID，在主体中以 eventId 重复出现。

载荷

一层描述事件的信封，加上一个描述回复的 data 对象。

{
  "eventId": "8f2c1d7a-4b09-4e5c-9a13-6d0f8b2e77c4",
  "eventType": "FORM_RESPONSE",
  "createdAt": "2026-08-26T09:14:22.481Z",
  "data": {
    "responseId": "Qh3Rk9wZm1sVtY7cN2xP",
    "formId": "7bTn4Kq2Wx",
    "formName": "Workshop signup",
    "createdAt": "2026-08-26T09:14:22.481Z",
    "fields": [
      {
        "key": "V1StGXR8_Z5jdHi6B-myT",
        "label": "Full name",
        "type": "INPUT_TEXT",
        "value": "Mira Kaya"
      },
      {
        "key": "kM4pQz7LxAe2Rn0BsTvUw",
        "label": "Which session?",
        "type": "MULTIPLE_CHOICE",
        "value": "c9XbNf3JdQ",
        "options": [
          { "id": "c9XbNf3JdQ", "text": "Morning" },
          { "id": "eR2mYt8KpL", "text": "Afternoon" }
        ]
      },
      {
        "key": "zA6cWn1FyH4tXd9QrLbEs",
        "label": "How likely are you to recommend us?",
        "type": "LINEAR_SCALE",
        "value": 9
      }
    ]
  }
}

属性	说明
eventId	本次投递的唯一 ID。
eventType	始终为 FORM_RESPONSE。
createdAt	回复提交的时间，UTC 的 ISO 8601 时间戳。
data.responseId	已存储回复的 ID。
data.formId	表单的 ID，和公开链接里出现的那个相同。
data.formName	表单标题的纯文本形式，已去除所有格式。
data.fields	每道已回答的问题一条。

fields 内部

每一条都带四个属性，带选项的问题还会多带一个。

属性	说明
key	问题的永久 ID。无论文案怎么改它都不变，因此请按它匹配，而不是按标签。
label	编辑器中写下的问题。
type	问题类型，取自下面的列表。
value	回答，采用该问题存储时的形态。
options	仅出现在带选项的问题上：每个选项的 ID 和文本，方便您把回答还原成标签。

只有答过的问题会送达

填写者没有碰过的问题不会以空值发送，而是根本不在数组里；被条件逻辑隐藏的问题更是完全不会出现。请按 key 查找每个回答，不要依赖位置或固定的条目数量。

选择题的回答是 ID，不是标签

下拉菜单或单选的回答是所选选项的 ID，复选框、多选或排序的回答是一组选项 ID 的数组。请对照同一条目上的 options 列表还原它们。排序题的回答保留填写者排出的顺序。

“其他”选项

填写者在“其他”输入框里写字时，值不是选项 ID，而是文本 __OTHER__: 加上他们输入的内容。去掉这个前缀即可读到回答。

"value": "__OTHER__:Heard about it from a friend"

文件与签名

文件上传的回答是指向 Fillio 存储中该文件的下载链接。签名的回答是 base64 PNG data URL，可以直接保存或显示。

字段类型

type 是稳定的公开名称，因此 Fillio 内部的改动不会波及您的集成。Fillio 无法映射的一律以 INPUT_TEXT 送达。

类型	问题	值
INPUT_TEXT	短回答	文本
TEXTAREA	长回答	文本
INPUT_EMAIL	邮箱	文本
INPUT_PHONE_NUMBER	电话号码	文本
INPUT_NUMBER	数字	数字的文本形式，与输入时完全一致
INPUT_LINK	链接	文本
INPUT_DATE	日期	日期，格式为 YYYY-MM-DD
INPUT_TIME	时间	时间，24 小时制的 HH:MM
DROPDOWN	下拉菜单	一个选项 ID
MULTIPLE_CHOICE	单选按钮	一个选项 ID
CHECKBOXES	复选框	选项 ID 的数组
MULTI_SELECT	多选下拉	选项 ID 的数组
RATING	星级评分	一个数字
LINEAR_SCALE	线性量表	一个数字
RANKING	排序	选项 ID 的数组，按填写者排出的顺序
FILE_UPLOAD	文件上传	一个下载链接
SIGNATURE	签名	一个 base64 PNG data URL

如果您的端点没有响应

Fillio 会等十秒。超时、连接错误或任何 2xx 之外的状态码都算投递失败，到此为止：没有重试，也没有可回放的队列。

回复本身不受任何影响。它在请求发出之前就已存好，无论您的端点如何反应都留在您的面板里，因此即便某次投递丢失，面板仍是完整的记录。

没有签名机制

Fillio 不对请求签名，也不发送共享密钥，因此仅凭主体无法证明它从哪里来。如果您的端点必须确认来源，就给它一个只有您知道的地址：一段又长又难猜的路径或查询串。从别处到达的内容一律视为不可信。

每次投递都带有自己的事件 ID，X-Fillio-Event-Id 请求头和主体中都有。记录下已经处理过的 ID，是让端点可以安全地被重复调用的最简单办法。

提示

把 webhook 指向任意一个请求检查服务，然后自己提交一次表单。您会看到表单产生的确切载荷，里面带着您自己的字段 ID。这是写好这一侧映射最快的办法。