Webhook 负载

每个 NueForm webhook 请求在请求体中发送一个 JSON 负载。本页记录了每种事件类型的完整负载模式。

通用结构

所有 webhook 负载共享这些顶级字段：

字段	类型	描述
`event`	`string`	事件类型（例如 `form.submitted`）
`formId`	`string`	表单的唯一 ID
`formTitle`	`string`	提交时表单的标题
`responseId`	`string`	回复的唯一 ID
`answers`	`array`	答案对象数组
`submittedAt`	`string`	事件分发时的 ISO 8601 时间戳

`form.submitted` 负载

这是受访者提交完整表单回复时发送的负载。

完整示例

json

{
  "event": "form.submitted",
  "formId": "507f1f77bcf86cd799439011",
  "formTitle": "Customer Feedback Survey",
  "responseId": "507f1f77bcf86cd799439022",
  "answers": [
    {
      "questionId": "507f1f77bcf86cd799439033",
      "value": "Jane Doe"
    },
    {
      "questionId": "507f1f77bcf86cd799439044",
      "value": "jane@example.com"
    },
    {
      "questionId": "507f1f77bcf86cd799439055",
      "value": 4
    },
    {
      "questionId": "507f1f77bcf86cd799439066",
      "value": "The onboarding flow was smooth and intuitive."
    },
    {
      "questionId": "507f1f77bcf86cd799439077",
      "value": ["Feature A", "Feature C"]
    },
    {
      "questionId": "507f1f77bcf86cd799439088",
      "value": true
    }
  ],
  "submittedAt": "2025-03-15T14:32:07.123Z"
}

字段参考

顶级字段

event --- string

此事件类型始终为 "form.submitted"。

formId --- string

表单的 MongoDB ObjectId。这是一个 24 字符的十六进制字符串。

formTitle --- string

webhook 触发时表单的可读标题。请注意，如果您后来重命名表单，之前已发送的 webhooks 仍然包含旧标题。

responseId --- string

存储回复的 MongoDB ObjectId。您可以使用它通过 Responses API 获取完整回复，或作为幂等键去重 webhook 传递。

submittedAt --- string

ISO 8601 时间戳，指示 webhook 分发的时间。这是在分发时生成的，将非常接近（但不一定完全相同于）数据库中回复的 submittedAt 字段。

答案对象

answers 数组中的每个条目代表单个问题的回复：

字段	类型	描述
`questionId`	`string`	问题的 MongoDB ObjectId
`value`	`any`	受访者的答案（格式因问题类型而异）

按问题类型的答案值

每个答案对象中的 value 字段因问题类型而异。以下是每种类型的格式：

文本输入

问题类型	值类型	示例
`short_text`	`string`	`"Jane Doe"`
`long_text`	`string`	`"I really enjoyed the product..."`
`email`	`string`	`"jane@example.com"`
`phone`	`string`	`"+1 (555) 123-4567"`
`number`	`number`	`42`
`url`	`string`	`"https://example.com"`

选择题

问题类型	值类型	示例
`multiple_choice`（单选）	`string`	`"Option A"`
`multiple_choice`（多选）	`array<string>`	`["Option A", "Option C"]`
`dropdown`	`string`	`"United States"`
`yes_no`	`boolean`	`true`
`picture_choice`（单选）	`string`	`"choice_id_abc123"`
`picture_choice`（多选）	`array<string>`	`["choice_id_abc123", "choice_id_def456"]`

对于 multiple_choice 问题，当 allowMultiple 为 false 时值为单个字符串，当 allowMultiple 为 true 时为字符串数组。如果受访者选择了"其他"选项，数组中将包含他们的自由文本输入作为字符串。

评分题

问题类型	值类型	示例	范围
`rating`	`number`	`4`	1 到 `steps`（默认 5）
`opinion_scale`	`number`	`7`	`min` 到 `max`
`nps`	`number`	`9`	0 到 10

日期和时间

问题类型	值类型	示例
`date`	`string`	`"2025-03-15"`

日期字符串格式匹配问题上配置的 dateFormat 属性（默认为 YYYY-MM-DD）。

法律条款和陈述

问题类型	值类型	示例
`legal`	`boolean`	`true`
`statement`	`string`	`""`（始终为空——陈述不收集数据）

排序

问题类型	值类型	示例
`ranking`	`array<string>`	`["Speed", "Price", "Quality"]`

数组反映受访者选择的顺序，从第一到最后。

矩阵

问题类型	值类型	示例
`matrix`	`object`	`{ "Speed": "Satisfied", "Price": "Neutral" }`

对象将行标签映射到每行所选的列标签。

文件上传

问题类型	值类型	示例
`file_upload`	`string`	`"https://storage.nueform.com/uploads/abc123.pdf"`

值为上传文件在 NueForm 存储中的 URL。

签名和绘图

问题类型	值类型	示例
`signature`	`string`	`"data:image/png;base64,iVBOR..."`
`drawing`	`string`	`"data:image/png;base64,iVBOR..."`

两者都返回捕获图像的 base64 编码 PNG data URI。

录制

问题类型	值类型	示例
`recording`	`string`	`"https://storage.nueform.com/recordings/abc123.webm"`

值为上传录制文件的 URL。

复合问题

复合问题类型（contact_info、address、question_group、multi_question_page）在 answers 数组中产生多个答案条目——每个子字段一个。每个子字段答案使用子字段自己的 questionId。

例如，一个 contact_info 问题可能产生：

json

[
  { "questionId": "first_name", "value": "Jane" },
  { "questionId": "last_name", "value": "Doe" },
  { "questionId": "email", "value": "jane@example.com" },
  { "questionId": "phone_number", "value": "+1 555-0100" },
  { "questionId": "company", "value": "Acme Inc." }
]

测验结果

对于以测验模式运行的表单（knowledge_quiz、lead_qualification 或 match_quiz），存储的回复包含 quizResults 对象。虽然此对象不直接包含在 webhook 负载中，但您可以使用 webhook 中的 responseId 通过 Responses API 检索它。

quizResults 对象具有以下结构：

json

{
  "formMode": "knowledge_quiz",
  "score": 7,
  "correctAnswers": 7,
  "totalScorableQuestions": 10,
  "maxScore": 10,
  "matchedEndingId": "507f1f77bcf86cd799439099"
}

字段	类型	描述
`formMode`	`string`	测验模式：`knowledge_quiz`、`lead_qualification` 或 `match_quiz`
`score`	`number`	受访者的总分
`correctAnswers`	`number`	正确回答的问题数（仅知识测验；其他模式为 `0`）
`totalScorableQuestions`	`number`	计入分数的问题总数
`maxScore`	`number`	可获得的最高分数
`matchedEndingId`	`string` 或 `undefined`	根据分数显示给受访者的结束页面 ID
`endingTallies`	`object` 或 `undefined`	仅匹配测验：将每个结束页面 ID 映射到其计数

元数据

存储的回复还可能包含一个 metadata 对象，其中包含通过 URL 参数传递的隐藏字段。这可通过 Responses API 获取，但不包含在 webhook 负载中。

json

{
  "hiddenFields": {
    "utm_source": "google",
    "utm_campaign": "spring_sale",
    "user_id": "ext_12345"
  }
}

要访问 webhook 传递回复的元数据，请使用 responseId 获取：

bash

curl https://app.nueform.com/api/v1/forms/FORM_ID/responses/RESPONSE_ID \
  -H "Authorization: Bearer nf_your_api_key"

HTTP 头

每个 webhook 请求包含这些 HTTP 头：

头	值
`Content-Type`	`application/json`
`X-NueForm-Signature`	原始请求体的 HMAC-SHA256 十六进制摘要

有关如何验证签名，请参阅验证。

负载大小

Webhook 负载通常很小（低于 10 KB）。大小主要取决于问题数量和文本答案的长度。文件上传答案包含 URL（而非文件内容），因此不会显著增加负载大小。

后续步骤

验证 --- 验证 webhook 签名
测试 --- 在本地测试 webhook 负载
事件 --- 事件类型和传递保证

通用结构

form.submitted 负载

完整示例

字段参考

顶级字段

答案对象

按问题类型的答案值

文本输入

选择题

评分题

日期和时间

法律条款和陈述

排序

矩阵

文件上传

签名和绘图

录制

复合问题

测验结果

元数据

HTTP 头

负载大小

后续步骤

`form.submitted` 负载