NueForm 在您账户中发生特定事件时发送 webhook 通知。每个 webhook 请求在 JSON 负载中包含一个 event 字段，标识发生了什么。
当前事件
form.submitted
当受访者提交对您表单的完整回复时触发。
| 属性 | 值 |
|---|---|
| 事件名称 | form.submitted |
| 触发条件 | 受访者完成并提交表单回复 |
| 负载 | 表单详情、回复 ID、带时间戳的答案 |
| 增量表单 | 仅在回复标记为 complete 时触发 |
这是 NueForm 中的主要 webhook 事件。它对标准（单次提交）表单和增量提交表单都会触发，但仅在回复达到完成状态时触发。
何时触发：
- 标准表单：在受访者点击提交且回复保存后立即触发。
- 增量表单：仅在发送带有
complete: true的最终提交时触发。部分保存不会触发此事件。 - 问卷样式表单：在受访者点击提交时触发。在此之前自动保存的回答属于一份未完成的回复，不会触发此事件。
- 测验模式表单（知识测验、潜客评估、匹配测验）：负载中只包含答案。测验结果与回复一起保存——请使用负载中的
responseId通过 Responses API 获取（参见负载中的“测验结果”一节）。
不触发的情况：
- 增量表单上的部分提交（
complete不为true）。 - 问卷样式表单中，受访者点击提交之前自动保存的回答。
- 对现有回复的编辑（回复一旦提交即不可变）。
- 表单草稿或预览。
- 表单构建器预览中的测试提交。
有关完整的负载模式，请参阅负载。
计划中的未来事件
以下事件计划在未来版本中发布。它们尚不可用，但在此记录以便您在设计集成时考虑前向兼容性。
下面列出的未来事件可能会发生变化。请查看变更日志了解新事件发布的公告。
form.partial
将在启用增量提交的表单上保存部分回复时触发。这将允许您跟踪表单放弃情况，并跟进已开始但未完成的受访者。
| 属性 | 计划值 |
|---|---|
| 事件名称 | form.partial |
| 触发条件 | 创建或更新部分回复（仅限增量表单） |
| 负载 | 与 form.submitted 结构相同，completedAt 为 null |
form.completed
将在增量回复从部分过渡到完成时触发。这与 form.submitted 的区别在于，它明确表示之前的部分回复已被最终确认。
| 属性 | 计划值 |
|---|---|
| 事件名称 | form.completed |
| 触发条件 | 部分回复被标记为完成 |
| 负载 | 与 form.submitted 结构相同，包含所有累积的答案 |
form.published
将在表单被发布或重新发布时触发。
| 属性 | 计划值 |
|---|---|
| 事件名称 | form.published |
| 触发条件 | 通过仪表板或 API 发布表单 |
| 负载 | 表单 ID、标题、路径、版本号、发布时间戳 |
form.unpublished
将在表单被取消发布（下线）时触发。
| 属性 | 计划值 |
|---|---|
| 事件名称 | form.unpublished |
| 触发条件 | 通过仪表板或 API 取消发布表单 |
| 负载 | 表单 ID、标题、路径、取消发布时间戳 |
事件传递保证
了解 NueForm 如何传递 webhook 事件对于构建可靠的集成非常重要。
至多一次传递
NueForm 目前提供至多一次传递语义。每个事件发送一次，如果传递失败不会重试。这意味着：
- 如果您的端点暂时不可用，可能偶尔会丢失事件。
- 一份回复只会完成一次，因此 NueForm 对每个 webhook URL 最多发送一次该回复的事件。不过，每个已配置的 URL 都会各自收到一次传递：如果同一个 URL 既被设为表单 webhook，又被设为全局 webhook，它会收到每个事件两次。此外，如果相同的回答被再次提交（例如网络错误后重试提交），就会创建第二份回复，它有自己的
responseId和自己的事件。 - 您应该设计集成以容忍丢失的事件。
无自动重试
如果您的端点不可达、返回错误状态码或未在 5 秒超时窗口内响应，此次传递即告失败，且不会重试。NueForm 会记录这次失败的尝试，但不会将其排队或重新发送。
由于没有自动重试，我们强烈建议通过定期轮询 Responses API 来补充 webhooks，以捕获端点可能遗漏的任何事件。
排序
Webhook 事件按发生顺序分发，但由于它们是并行发送到多个 URL 且网络条件各异，传递顺序不保证。如果您的应用需要严格排序，请使用负载中的 submittedAt 时间戳在收到后对事件排序。
超时
NueForm 等待您的端点响应最多 5 秒。如果您的端点未在此窗口内响应，请求将被中止。您的端点应尽快返回 2xx 状态码，并将任何繁重处理推迟到后台任务。
幂等性
您的端点可能会多次收到同一个事件——例如，同一个 URL 既被设为表单 webhook，又被设为全局 webhook 时。使用负载中的 responseId 字段作为幂等键以安全地去重。
最佳实践
快速响应。 立即返回
200 OK并异步处理 webhook 数据。NueForm 有 5 秒超时。验证签名。 在信任负载之前始终验证
X-NueForm-Signature头。请参阅验证。使用幂等键。 存储已处理的
responseId值并跳过重复项。定期核对。 通过定期轮询 Responses API 补充实时 webhooks，以捕获任何遗漏的事件。
监控您的端点。 跟踪 webhook 端点的响应时间和错误率。如果您的端点持续失败，请考虑在 webhook 接收器和处理逻辑之间实现队列（例如 SQS、Redis）。