Webhook 负载

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

通用结构

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

form.submitted 负载

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

完整示例

{
  "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
    }
  ],
  "respondent": {
    "id": "507f1f77bcf86cd799439016",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "auth_method": "sso"
  },
  "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 字段。

respondent --- object 或 null

提交回复的已登录用户的身份，仅当表单要求登录（requireLogin: true）时才会公开。所有匿名提交均为 null。请参阅下方的 受访者身份 以获取完整模式和行为。

答案对象

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

按问题类型的答案值

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

文本输入

选择题

评分题

日期和时间

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

法律条款和陈述

排序

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

矩阵

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

文件上传

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

签名和绘图

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

录制

值为上传录制文件的 URL。

复合问题

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

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

[
  { "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." }
]

受访者身份 {#respondent-identity}

当表单配置了 requireLogin: true 时，每次接受的提交都会绑定到已登录的用户。Webhook 负载通过 respondent 字段向表单所有者公开该身份。对于所有其他提交，该字段为 null。

模式

{
  "respondent": {
    "id": "507f1f77bcf86cd799439016",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "auth_method": "sso"
  }
}

何时填充 respondent

respondent 仅在以下情况下填充：

1. 表单将 requireLogin 设置为 true，并且
2. 提交者因为表单要求而在提交前登录。

当 requireSsoLogin 也为 true 时，只有通过 SSO 成为表单团队成员的用户才能进入提交步骤，因此每个填充的 respondent 都将具有 auth_method: "sso"。

何时 respondent 为 null

为了下游解析的可预测性，该字段始终存在于 JSON 中，并在以下任一情况下为 null：

• 表单不要求登录（requireLogin 为 false）。
• 提交者是匿名的。
• 回复是通过提交后同意流程（"认领此回复"提示）保存的。永远不会有附加身份的同意保存回复出现在 webhook 负载中——它们仅存储在用户的"我的回复"视图中，不会公开给 webhook 接收者。

测验结果

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

quizResults 对象具有以下结构：

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

元数据

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

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

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

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

HTTP 头

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

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

负载大小

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

后续步骤

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