Webhooks API

配置表单级和全局 Webhook，实现实时响应通知。

Webhook 允许您在表单收到新提交时接收实时 HTTP POST 通知。NueForm 支持两个级别的 Webhook：

表单 Webhook -- 每个表单一个 URL，接收该特定表单的提交。
全局 Webhook -- 最多 5 个 URL，接收您所有表单的提交。

Webhook 需要 Pro 套餐或更高版本。在免费套餐上尝试使用 Webhook 端点将返回 403 错误。

所有请求和响应体均使用 snake_case 字段命名。

Endpoints

GET/api/v1/forms/:id/webhooksPUT/api/v1/forms/:id/webhooksGET/api/v1/webhooksPUT/api/v1/webhooksGET/api/v1/webhooks/secretPOST/api/v1/webhooks/secret

获取表单 Webhook

GET/api/v1/forms/:id/webhooks

检索为特定表单配置的 Webhook URL。

路径参数

idstring必填

表单 ID

如果未配置 Webhook，webhook_url 将为 null。

响应

json

{
  "webhook_url": "https://example.com/hooks/nueform"
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

设置表单 Webhook

PUT/api/v1/forms/:id/webhooks

设置或清除特定表单的 Webhook URL。当收到提交时，NueForm 将向此 URL 发送包含响应数据的 HTTP POST 请求。

路径参数

idstring必填

表单 ID

请求体

urlstring or null必填

Webhook URL。必须是有效的 URL。设置为 null 可移除 Webhook。

请求示例

json

{
  "url": "https://example.com/hooks/nueform"
}

移除 Webhook：

json

{
  "url": null
}

响应

json

{
  "webhook_url": "https://example.com/hooks/nueform"
}

代码示例

bash

curl -X PUT "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/nueform" }'

列出全局 Webhook

GET/api/v1/webhooks

检索为您账户配置的所有全局 Webhook。全局 Webhook 会在您所有表单收到提交时触发。

响应

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

设置全局 Webhook

PUT/api/v1/webhooks

用提供的数组替换所有全局 Webhook。您最多可以配置 5 个全局 Webhook。每个 Webhook 可以单独启用或禁用。

请求体

webhooksarray必填

Webhook 对象数组（最多 5 个）

请求示例

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://slack-webhook.example.com/nueform",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

响应

json

{
  "webhooks": [
    {
      "url": "https://example.com/hooks/all-forms",
      "enabled": true
    },
    {
      "url": "https://slack-webhook.example.com/nueform",
      "enabled": true
    },
    {
      "url": "https://backup.example.com/hooks/nueform",
      "enabled": false
    }
  ]
}

代码示例

bash

curl -X PUT "https://api.nueform.io/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      { "url": "https://example.com/hooks/all-forms", "enabled": true },
      { "url": "https://backup.example.com/hooks/nueform", "enabled": false }
    ]
  }'

获取 Webhook 密钥

GET/api/v1/webhooks/secret

检索您的 Webhook 签名密钥。如果尚未存在密钥，系统会自动生成一个。密钥是由 32 个随机字节派生的 64 字符十六进制字符串。

使用此密钥通过验证 X-NueForm-Signature 头中的 HMAC-SHA256 签名来确认传入的 Webhook 请求确实来自 NueForm。

验证签名

当 NueForm 发送 Webhook 时，会包含一个 X-NueForm-Signature 头，其中包含请求体的 HMAC-SHA256 十六进制摘要。在您的 Webhook 处理程序中验证它以确保真实性。

响应

json

{
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
}

签名验证示例

javascript

const crypto = require("crypto");

function verifyWebhookSignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

重新生成 Webhook 密钥

POST/api/v1/webhooks/secret

生成新的 Webhook 签名密钥，替换现有密钥。重新生成后，所有 Webhook 投递将使用新密钥签名。

重新生成后，请立即更新您的 Webhook 接收端以使用新密钥。使用旧密钥签名的请求将无法通过验证。

响应

json

{
  "secret": "f0e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/webhooks/secret" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook 载荷格式

当表单收到提交时，NueForm 会向您配置的 Webhook URL 发送包含以下载荷的 POST 请求。

event 字段标识事件类型，response 对象包含完整的提交数据（包括所有答案）。

请求头

Content-Typeapplication/json

请求体内容类型

X-NueForm-Signaturestring

请求体的 HMAC-SHA256 十六进制摘要

X-NueForm-Eventstring

事件类型（例如 response.submitted）

载荷示例

json

{
  "event": "response.submitted",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "form_title": "Customer Feedback Survey",
  "response": {
    "id": "667a1b2c3d4e5f6a7b8c9d01",
    "submitted_at": "2026-02-27T15:42:00.000Z",
    "completed_at": "2026-02-27T15:45:30.000Z",
    "answers": [
      {
        "question_id": "66a1b2c3d4e5f6a7b8c9d001",
        "question_title": "What is your name?",
        "value": "Jane Smith"
      }
    ]
  }
}

错误响应

Webhook 端点返回的标准错误响应。

错误码

400Bad Request

URL 格式无效，超过 5 个全局 Webhook 上限，或缺少必填字段

401Unauthorized

缺少或无效的 API 密钥

403Forbidden

Webhook 需要 Pro 套餐或更高版本

404Not Found

表单未找到

500Server Error

服务器内部错误

错误示例

json

{
  "error": "Webhooks require a Pro plan or higher"
}

最后更新：2026年4月6日