NueForm 在您账户中发生特定事件时发送 webhook 通知。每个 webhook 请求在 JSON 负载中包含一个 event 字段，标识发生了什么。
当前事件
form.submitted
当受访者提交对您表单的完整回复时触发。
| 属性 | 值 |
|---|---|
| 事件名称 | form.submitted |
| 触发条件 | 受访者完成并提交表单回复 |
| 负载 | 表单详情、回复 ID、带时间戳的答案 |
| 增量表单 | 仅在回复标记为 complete 时触发 |
这是 NueForm 中的主要 webhook 事件。它对标准（单次提交）表单和增量提交表单都会触发，但仅在回复达到完成状态时触发。
何时触发：
- 标准表单：在受访者点击提交且回复保存后立即触发。
- 增量表单：仅在发送带有
complete: true的最终提交时触发。部分保存不会触发此事件。 - 测验模式表单（知识测验、潜客评估、匹配测验）：负载中除答案外还包含测验评分结果。
不触发的情况：
- 增量表单上的部分提交（
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 的传递系统收到同一提交的重复事件。
- 您应该设计集成以容忍丢失的事件。
无自动重试
如果您的端点不可达、返回错误状态码或未在 5 秒超时窗口内响应，webhook 传递将被静默丢弃。NueForm 不会排队或重试失败的传递。
由于没有自动重试，我们强烈建议通过定期轮询 Responses API 来补充 webhooks，以捕获端点可能遗漏的任何事件。
排序
Webhook 事件按发生顺序分发，但由于它们是并行发送到多个 URL 且网络条件各异，传递顺序不保证。如果您的应用需要严格排序，请使用负载中的 submittedAt 时间戳在收到后对事件排序。
超时
NueForm 等待您的端点响应最多 5 秒。如果您的端点未在此窗口内响应，请求将被中止。您的端点应尽快返回 2xx 状态码，并将任何繁重处理推迟到后台任务。
幂等性
虽然 NueForm 在设计上不会发送重复事件，但网络条件（如 TCP 重传）理论上可能导致您的端点多次接收相同的负载。使用负载中的 responseId 字段作为幂等键以安全地去重。
最佳实践
**快速响应。**立即返回
200 OK并异步处理 webhook 数据。NueForm 有 5 秒超时。**验证签名。**在信任负载之前始终验证
X-NueForm-Signature头。请参阅验证。**使用幂等键。**存储已处理的
responseId值并跳过重复项。**定期核对。**通过定期轮询 Responses API 补充实时 webhooks，以捕获任何遗漏的事件。
**监控您的端点。**跟踪 webhook 端点的响应时间和错误率。如果您的端点持续失败，请考虑在 webhook 接收器和处理逻辑之间实现队列（例如 SQS、Redis）。