SetFN
SetFNDocs2026年10月27日

Webhook 设置

Webhook 是其他程序向 SpaceBuilder 的指定文件夹自动传送文件时使用的专用接收地址。例如，可以将扫描仪、业务系统或自动化程序生成的文件在无需人工操作的情况下保存到文件夹中。

本页面介绍管理员如何设置整个服务器的 Webhook 使用范围和限制。关于在实际文件夹中创建 Webhook 并使用接收地址的方法，请参阅文件夹 Webhook 使用方法。

设置前的确认事项

  • 要从外部调用 Webhook，必须准备好可以访问 SpaceBuilder 的地址。
  • Webhook 地址中包含用于认证的密钥。完整地址仅在管理员和对接程序负责人之间共享。
  • 公开到互联网时，建议使用 HTTPS。
  • 接收的文件越大，服务器的内存和存储空间占用就越高。

Webhook 策略设置

Webhook 使用设置

在管理员设置中选择 Webhook 功能的使用对象和安全等级。

项目说明
启用入站 Webhook开启服务器的 Webhook 接收功能。关闭后，即使是已创建的 Webhook 地址也无法接收文件。
允许用户签发 API 密钥允许在文件夹中创建和管理 Webhook 接收地址。关闭后，包括管理员在内的任何人都无法在文件夹中新建 Webhook。
允许个人文件夹 Webhook除团队文件夹外，还允许在用户的个人文件夹中创建 Webhook。需要向个人文件夹接收文件时开启。
允许保存到子文件夹允许用户为每个 Webhook 开启保存到子文件夹。开启后的 Webhook 会按文件名中附带的子路径保存，并创建不存在的文件夹。默认值为关闭；关闭期间，即使已设置为允许的 Webhook 也不会接收带有子路径的文件。
强制 Webhook 签名验证（安全）对新建或更换密钥的 Webhook 应用额外的签名验证。这是在调用程序支持 HMAC 签名时使用的安全功能，默认值为关闭。

容量与请求限制设置

设置通过 Webhook 一次可接收的大小和请求次数。在一般环境中直接使用默认值即可。

项目默认值说明
最大负载大小8 MB通过 Webhook 一次可接收的文件和请求信息的总大小。这是服务器的默认值，需要接收更大的文件时可以调高。
全局请求速率限制每秒 5 次限制短时间内请求过度集中。仅在正常请求受到限制时调整该值。

负载是指通过 Webhook 传送的文件与请求信息合并后的全部内容。由于还包含文件以外的信息，显示的大小可能略大于实际文件。

超过设置的大小时，文件不会被保存，并返回 413 Request Entity Too Large 响应。对于经常传送大文件的环境，更适合使用普通的文件上传方式。

调高一次可接收的大小

需要通过 Webhook 接收大于 8 MB 的文件时，按如下方式更改。

  1. 在管理员页面中打开服务配置 > 文件区域，并展开 Webhook（自动数据接收） 卡片。
  2. 在 最大负载大小 输入框中输入所需的大小。
  3. 在输入框右侧选择 MB 或 GB 单位。
  4. 保存设置。
  5. 先用小文件确认传送正常，再传送所需的文件。

例如，要接收最大约 20 MB 的文件，则在数字中输入 20，单位选择 MB。服务器支持的设置范围为 1 KB~1 GB。

将 Webhook 公开到互联网时，如果在 Cloudflare 或 Nginx 上也设置请求限制，就可以在异常大量的请求到达服务器之前将其过滤掉。

推荐设置顺序

  1. 开启 启用入站 Webhook。
  2. 为了能在文件夹中创建 Webhook，开启 允许用户签发 API 密钥。
  3. 仅在需要向个人文件夹接收文件时，开启 允许个人文件夹 Webhook。
  4. 容量和请求限制使用默认值。
  5. 保存设置后，在实际要使用的文件夹中创建 Webhook。
  6. 先传送一个小的测试文件，确认保存位置和权限。

出现问题时

现象确认内容
无法接收文件确认是否已开启入站 Webhook 功能并允许用户签发 API 密钥。
401 响应确认 Webhook 地址的密钥或签名标头是否正确。
403 响应确认是否允许个人文件夹以及目标文件夹的权限。
409 响应确认 Webhook 是否已暂停，或是否与同名文件处理策略冲突。
413 响应确认请求总大小是否未超过最大负载大小。
接收后服务器变慢降低负载大小和请求次数，并确认 OCR 和文档转换任务是否过度集中。

相关文档