Webhooks 概述 | NueForm Docs

Webhooks 让您的应用在 NueForm 中发生事件时接收实时 HTTP 通知。您无需轮询 API 获取新回复，NueForm 会在表单提交时立即将数据推送到您的服务器。

Webhooks 在 Pro 计划（$29/月）及以上可用。Entrepreneur（免费）计划用户需要升级才能使用 webhooks。

Webhooks 工作原理

当受访者提交表单时，NueForm 会立即向您配置的每个 webhook URL 发送 HTTP POST 请求。请求体包含带签名的 JSON 负载，其中包括事件类型、表单详情和提交的答案。

流程如下：

受访者完成并提交您的表单。
NueForm 验证答案并存储回复。
NueForm 构建包含事件数据的 JSON 负载。
NueForm 使用您的 webhook 密钥通过 HMAC-SHA256 对负载签名。
NueForm 将负载作为 POST 请求发送到每个配置的 URL。
您的服务器接收请求，验证签名并处理数据。

Webhook 传递是即发即忘和非阻塞的。Webhook 失败永远不会影响提交流程——无论您的 webhook 端点是否可达，受访者始终会看到成功的提交。

单表单与全局 Webhooks

NueForm 支持两种类型的 webhook 配置：

单表单 Webhooks

每个表单可以有自己专用的 webhook URL。这在您希望不同表单通知不同系统时很有用——例如将支持表单提交发送到帮助台，将反馈表单提交发送到分析管道。

您可以通过以下方式设置单表单 webhook URL：

NueForm 仪表板 --- 打开表单设置并输入 webhook URL。
API --- 使用 Webhooks API 以编程方式设置或更新 URL。

bash

curl -X PUT https://app.nueform.com/api/v1/webhooks/form/FORM_ID \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhooks/nueform" }'

全局 Webhooks

全局 webhooks 为您账户中的每个表单触发。它们适用于集中式日志记录、分析或需要处理所有提交（无论来自哪个表单）的 CRM 集成。

您最多可以配置 5 个全局 webhooks，每个都可以单独启用或禁用。

bash

curl -X PUT https://app.nueform.com/api/v1/webhooks/global \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "url": "https://analytics.example.com/nueform", "enabled": true },
      { "url": "https://crm.example.com/inbound", "enabled": true },
      { "url": "https://staging.example.com/test", "enabled": false }
    ]
  }'

传递顺序

提交表单时，NueForm 并行向所有适用的 URL 分发 webhooks：

表单的单表单 webhook URL（如果已设置）。
所有已启用的全局 webhook URL。

每个目标接收相同的负载和相同的签名。

Webhooks 何时触发

目前，webhooks 在单个事件上触发：

事件	触发条件
`form.submitted`	受访者提交完整的回复

对于启用了增量提交的表单，webhook 仅在回复标记为完成时触发——部分保存不会触发 webhooks。

有关完整的事件参考和计划中的未来事件，请参阅事件。

Webhook 安全

每个 webhook 请求都包含一个 X-NueForm-Signature 头，其中包含请求体的 HMAC-SHA256 十六进制摘要。您应始终在处理 webhook 数据之前验证此签名，以确保请求确实来自 NueForm。

您的 webhook 密钥在首次访问时自动生成，可随时通过 API 或仪表板重新生成。

有关实现细节和代码示例，请参阅验证。

传递特性

属性	值
HTTP 方法	`POST`
内容类型	`application/json`
超时	5 秒
重试策略	无自动重试（即发即忘）
签名头	`X-NueForm-Signature`
签名算法	HMAC-SHA256（十六进制摘要）

NueForm 目前使用即发即忘的传递模型，超时为 5 秒，无自动重试。如果您的端点不可达或返回错误，webhook 传递将被静默丢弃。请设计您的集成以处理偶尔的遗漏传递——例如定期通过 Responses API 进行核对。

快速入门

要开始接收 webhooks：

获取您的 webhook 密钥 --- 调用 GET /api/v1/webhooks/secret 或在仪表板的开发者设置中找到。如果您还没有密钥，NueForm 会自动生成一个。
设置 webhook URL --- 配置单表单 URL 或添加全局 webhook。
实现您的端点 --- 构建一个接受 POST 请求、验证签名并处理负载的 HTTP 端点。
测试它 --- 使用 webhook.site 或 ngrok 等工具在上线前验证传递。有关详细说明，请参阅测试 Webhooks。

后续步骤

事件 --- 了解 webhook 事件类型
负载 --- 查看完整的负载模式和示例
验证 --- 实现 HMAC-SHA256 签名验证
测试 --- 在本地开发期间测试 webhooks