跳到主要内容

回调集成（Webhook）

概览​

OPL 数据空间提供三类 Webhook 集成，用于把实例内事件通知到外部系统，或者把外部消息投递进 OPL 数据空间：

  1. Admin Webhook：管理员级，全局新用户注册通知
  2. User Webhook：用户级，聊天回复生成完成通知
  3. Channel Webhooks：入站 Webhook，把外部消息发进指定频道

这些 Webhook 可以接入 Discord、Slack，以及任何支持 webhook 的系统。

1. Admin Webhook：新用户通知​

用于在新用户注册时通知管理员。

典型场景​

  • 在 Slack / Discord 里实时收到新账号注册通知

配置方式​

管理面板​

  1. 以管理员身份登录
  2. 前往 管理员面板 > 设置 > 通用
  3. 找到 Webhook URL
  4. 填入外部服务提供的 webhook 地址
  5. 点击 保存

环境变量​

也可以使用 WEBHOOK_URL 配置，详见 环境变量文档。

Payload 示例​

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

2. User Webhook：聊天回复通知​

用户可以在模型完成回复后收到通知，适合处理耗时较长的任务。

典型场景​

  • 你提交了一个几分钟后才会完成的复杂请求，不需要一直盯着标签页

工作方式​

只有当你 没有在主动使用 WebUI 时，通知才会发出。如果当前标签页处于激活状态，Webhook 不会触发。

启用 / 禁用​

管理员可以在以下位置统一控制：

  • 管理员面板 > 设置 > 通用 > Features 中切换 User Webhooks
  • 或通过 ENABLE_USER_WEBHOOKS 环境变量关闭

用户配置​

  1. 点击左下角头像
  2. 前往 设置 > 账号
  3. 找到 通知 Webhook
  4. 填入个人 webhook URL
  5. 点击 保存

Payload 示例​

{
  "event": "chat_response",
  "chat": {
    "id": "abc-123-def-456",
    "title": "My Awesome Conversation",
    "last_message": "This is the prompt I submitted."
  }
}

3. Channel Webhooks：外部消息接入频道​

Channel Webhooks 允许外部服务、脚本、CI/CD、监控系统等直接把消息发进 OPL 数据空间的频道。

典型场景​

  • Prometheus / Grafana / Nagios 报警推送到团队频道
  • GitHub Actions、GitLab CI、Jenkins 构建状态通知
  • 与 n8n、Zapier 或自定义自动化脚本打通

工作方式​

每个频道都可以有多个 webhook。每个 webhook 都有：

  • 一个唯一 URL
  • 一个显示名称
  • 一个可选头像
  • 最近一次使用时间

这些消息会以 webhook 身份显示，而不是某个普通用户。

管理 webhook​

只有 频道管理员 或 系统管理员 能创建和管理频道 webhook。

创建​

  1. 打开目标频道
  2. 点击频道菜单（⋮）→ Edit Channel
  3. 在设置弹窗中找到 Webhooks
  4. 点击 Manage
  5. 点击 New Webhook
  6. 配置：
    • Name
    • Profile Image（可选）
  7. 保存
  8. 用 Copy URL 复制生成的 webhook URL

URL 格式​

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

任何拥有这个 URL 的人都能向该频道发消息，因此必须妥善保管。

更新​

  1. 打开 Webhooks 弹窗
  2. 展开目标 webhook
  3. 修改名称或头像
  4. 保存

更新名称和头像不会改变 URL；旧消息也不会被回溯修改。

删除​

  1. 打开 Webhooks 弹窗
  2. 展开目标 webhook
  3. 点击删除图标
  4. 确认

删除后，该 URL 会立刻失效。旧消息仍会保留，但作者会显示为 “Deleted Webhook”。

通过 webhook 发消息​

向 webhook URL 发送 POST 请求，body 为 JSON：

{
  "content": "Your message content here"
}

cURL 示例​

curl -X POST "https://your-instance.com/api/channels/webhooks/{webhook_id}/{token}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Deployment to production completed successfully!"}'

Python 示例​

import requests

webhook_url = "https://your-instance.com/api/channels/webhooks/{webhook_id}/{token}"
message = {
    "content": "Build #1234 failed: Unit tests did not pass."
}

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

成功时通常会返回：

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

安全注意事项​

  • webhook URL 本身包含认证 token，不要放进公开仓库或日志
  • 只把 URL 给可信系统
  • 发送侧应自行校验消息内容
  • 一旦 URL 泄露，删除旧 webhook 并重新创建

webhook 身份显示​

  • 消息会显示 webhook 的名称和头像
  • 角色会标为 webhook
  • 即使 webhook 已删除，旧消息仍保留，但名称会变成 “Deleted Webhook”

故障排查​

如果没有收到 webhook 通知，优先检查：

  • URL 是否正确
  • 外部服务配置是否正确
  • OPL 数据空间所在服务器是否能向外发请求
  • 网络、防火墙或代理是否阻断了出站请求