跳到主要内容

Webhook 集成

概述​

Open WebUI 提供了三种不同的 Webhook 集成，以帮助您及时了解实例中发生的事件并启用外部集成。这些 Webhook 允许您在外部服务（如 Discord、Slack 或任何其他支持接收 Webhook 的应用程序）中接收自动通知，同时允许从外部服务向 Open WebUI 频道发布消息。

目前提供以下三种类型的 Webhook：

  1. Admin Webhook： 系统级 Webhook，在有新用户注册时通知管理员。
  2. User Webhook： 个人 Webhook，当用户的聊天响应生成完毕时通知个人用户，这对于长时运行的任务特别有用。
  3. Channel Webhooks： 接收式 Webhook，允许外部服务向特定频道发布消息。

1. Admin Webhook：新用户通知​

该 Webhook 旨在让管理员能够监控 Open WebUI 实例上的新用户注册情况。

使用场景​

  • 用户注册跟踪： 每当有新用户创建账户时，在专用的 Slack 或 Discord 频道中接收实时通知。这有助于您跟踪用户增长情况并欢迎新成员。

配置​

您可以通过以下两种方式配置管理员 Webhook：

选项 1：通过 Admin Panel​

  1. 以管理员身份登录。
  2. 导航至 Admin Panel > Settings > General。
  3. 找到 "Webhook URL" 字段。
  4. 输入由您的外部服务（例如 Discord、Slack）提供的 Webhook URL。
  5. 点击 "Save"。

选项 2：通过环境变量​

您还可以使用 WEBHOOK_URL 环境变量来设置 Webhook URL。有关详细信息，请参阅 环境变量配置 文档。

Payload 格式​

当有新用户注册时，Open WebUI 将发送一个 POST 请求到配置的 URL，其中包含一个带有新用户详细信息的 JSON payload。

Payload 示例：

{
  "event": "new_user",
  "user": {
    "email": "tim@example.com",
    "name": "Tim"
  }
}

2. User Webhook：聊天响应通知​

该 Webhook 允许个人用户在模型完成对其 Prompt 的响应生成时接收通知。这对于需要耗费较长时间且您可能会切走 Open WebUI 标签页的任务特别有用。

使用场景​

  • 长时运行任务提醒： 如果您提交了一个需要花费数分钟处理的复杂 Prompt，您可以关闭浏览器标签页，并在响应就绪的瞬间收到通知。这使您可以处理其他任务，而无需不断检查 Open WebUI 界面。

工作原理​

该通知仅在您未处于活跃使用 WebUI 的状态下才会发送。如果您打开了标签页并且焦点在上面，Webhook 将不会被触发，从而避免不必要的通知。

启用/禁用 User Webhooks​

User Webhooks 默认是禁用的。管理员可以根据需要为所有用户启用此功能，或者保持禁用状态以防止外部请求。

这可以通过以下两种方式完成：

  1. 直接在 Admin Panel 中：

    • 前往 Admin Panel > Settings > General > Features。
    • 切换 "User Webhooks" 开关。

  2. 使用环境变量：

    • 在后端配置中将环境变量 ENABLE_USER_WEBHOOKS 设置为 False。这将全局禁用该功能并在用户个人资料中隐藏该设置。

配置​

  1. 点击左下角的头像以打开设置菜单。
  2. 导航至 Settings > Account。
  3. 找到 "Notification Webhook" 字段。
  4. 输入您的个人 Webhook URL。
  5. 点击 "Save"。

Payload 格式​

当聊天响应就绪且您处于非活跃状态时，Open WebUI 将发送一个 POST 请求到您的 Webhook URL，其中包含关于聊天的 JSON payload。

Payload 示例：

{
  "event": "chat_response",
  "chat": {
    "id": "abc-123-def-456",
    "title": "我的精彩对话",
    "last_message": "这是我提交的 Prompt。"
  }
}

3. Channel Webhooks：外部消息集成​

Channel Webhooks 允许外部服务、自动化工具或脚本直接向 Open WebUI 频道发布消息。这实现了与监控系统、CI/CD Pipeline、通知服务或任何自定义自动化的无缝集成。

使用场景​

  • 系统监控： 将监控工具（Prometheus、Grafana、Nagios）的警报直接发送到团队频道中。
  • CI/CD 集成： 将来自 GitHub Actions、GitLab CI 或 Jenkins 的构建状态通知发送到开发频道中。
  • 自定义自动化： 与 n8n、Zapier 或自定义脚本集成，以实现消息的自动发送。
  • 外部通知： 将来自外部服务的通知转发到您的 Open WebUI 工作区中。

工作原理​

每个频道可以有多个 Webhook。每个 Webhook 具有：

  • 外部服务可以 POST 到的唯一 Webhook URL
  • 显示为消息作者的显示名称
  • 可选的头像图片，用于直观地标识 Webhook 来源
  • 上次使用时间戳，用于跟踪 Webhook 的活跃状态

通过 Webhook 发布的消息会以该 Webhook 的身份显示在频道中，从而明确表明它们来自外部来源而不是普通用户。

管理 Channel Webhooks​

只有**频道管理员（Managers）和系统管理员（Administrators）**才可以为频道创建和管理 Webhook。

创建 Webhook​

  1. 导航到您要添加 Webhook 的频道。
  2. 点击频道菜单 (⋮) 并选择 Edit Channel。
  3. 在频道设置模态框中，找到 Webhooks 部分。
  4. 点击 Manage 打开 Webhooks 模态框。
  5. 点击 New Webhook 以创建一个新的 Webhook。
  6. 配置 Webhook：
    • Name： 将显示为消息作者的显示名称
    • Profile Image： （可选）上传一张代表此 Webhook 的图片
  7. 点击 Save 创建该 Webhook。
  8. 使用 Copy URL 按钮复制生成的 Webhook URL。

Webhook URL 格式​

{WEBUI_API_BASE_URL}/channels/webhooks/{webhook_id}/{token}

此 URL 是唯一的，并且包含认证 Token。任何拥有此 URL 的人都可以向频道发布消息，因此请妥善保管。

更新 Webhook​

  1. 从频道设置中打开 Webhooks 模态框。
  2. 点击您要编辑的 Webhook 以展开它。
  3. 根据需要修改 Name 或 Profile Image。
  4. 点击 Save 以应用更改。

更新名称或图片时，Webhook URL 保持不变。更新后发布的消息将显示新的名称/图片，但已发布的消息仍将保留发布时的 Webhook 身份。

删除 Webhook​

  1. 从频道设置中打开 Webhooks 模态框。
  2. 点击您要删除的 Webhook 以展开它。
  3. 点击 Delete（垃圾桶）图标。
  4. 确认删除。

一旦删除，Webhook URL 将立即失效。先前由该 Webhook 发布的消息将保留在频道中，但作者将显示为“已删除的 Webhook (Deleted Webhook)”。

通过 Webhook 发布消息​

要从外部服务发布消息，请发送一个带有 JSON payload 的 POST 请求到 Webhook URL。

请求格式​

接口端点： POST {webhook_url} 请求头： Content-Type: application/json 请求体：

{
  "content": "这里是您的消息内容"
}

示例：使用 cURL​

curl -X POST "https://your-instance.com/api/channels/webhooks/{webhook_id}/{token}" \
  -H "Content-Type: application/json" \
  -d '{"content": "部署到生产环境成功完成！🚀"}'

示例：使用 Python​

import requests

webhook_url = "https://your-instance.com/api/channels/webhooks/{webhook_id}/{token}"
message = {
    "content": "构建 #1234 失败：单元测试未通过。"
}

response = requests.post(webhook_url, json=message)
print(response.json())

响应格式​

成功时，Webhook 将返回：

{
  "success": true,
  "message_id": "abc-123-def-456"
}

安全注意事项​

  • URL 保护： Webhook URL 包含认证 Token。请妥善保管它们，不要将它们暴露在公共仓库或日志中。
  • 频道访问权限： 任何拥有 Webhook URL 的人都可以向频道发布消息。仅将 URL 分享给受信任的服务。
  • 消息内容： 在发送端验证并清理消息内容，以防止注入攻击。
  • 重新生成： 如果 Webhook URL 泄露，请删除该 Webhook 并创建一个新的 Webhook。

Webhook 身份标识​

通过 Webhook 发布的消息具有特殊的身份系统：

  • 它们会以该 Webhook 的 名称 和 头像图片 显示
  • 用户角色被标记为 "webhook"，以区别于普通用户
  • 如果某个 Webhook 被删除，它的消息仍将保持可见，但作者会显示为 "Deleted Webhook"，并且不再显示当前的 Webhook 名称
  • 每条消息都将其 Webhook ID 存储在元数据中，这使得即使 Webhook 稍后被修改或删除，也能够正确归因

故障排除​

如果您未收到 Webhook 通知，请检查以下几点：

  • 验证 URL： 确保 Webhook URL 正确，且已正确粘贴到设置字段中。
  • 服务配置： 仔细检查在外部服务（例如 Discord、Slack）中是否正确配置了 Webhook。
  • 防火墙/代理： 确保您的网络或防火墙没有阻止来自 Open WebUI 服务器的传出请求。
  • Open WebUI 日志： 检查 Open WebUI 服务器日志，了解是否有任何与 Webhook 失败相关的错误消息。
备注

Open WebUI 中的 Webhook 功能正在不断改进。请关注未来更新中的更多事件类型和自定义选项。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.