Webhook

xylplm2026/7/12大约 8 分钟使用文档其它Webhook媒体服务器

🪝 Webhook

Webhook 是一种轻量级的回调机制，允许外部服务在特定事件发生时通知 Media Saber。通过配置 Webhook，你可以实现第三方服务与 Media Saber 的实时通信，并自动触发相关操作。媒体服务器集成只是其中一种应用场景。

🎯 支持的 Webhook 类型

Media Saber 支持以下类型的 Webhook 集成：

Emby Webhook
Jellyfin Webhook
Plex Webhook
开放消息渠道 Webhook

💡 配置好 Emby / Jellyfin / Plex 的 Webhook 后：
可在媒体服务器中控制是否通过消息渠道推送，以及推送哪些事件
播放事件还会自动汇入观影报告，作为最精准的「实时」观看统计来源

🖥️ 在 Media Saber 中配置媒体服务 Webhook

推荐先在 Media Saber 完成媒体服务侧配置，再去媒体服务器后台粘贴地址。

1. 获取 Webhook 地址

进入 媒体服务 → 媒体服务器
新增或编辑 Emby / Jellyfin / Plex
保存后点击 Webhook 地址
按场景复制 内网地址 或 外网地址

新地址统一为：

http[s]://your-domain.com[:port]/api/v1/webhook/mediaServer/{媒体服务ID}?apiKey=your-api-key

旧地址 /api/v1/webhook/emby、/api/v1/webhook/plex 已废弃，请改用按媒体服务 ID 生成的新地址。

同内网优先使用内网地址，延迟更低也更稳定；媒体服务只能从外网访问 Media Saber 时，使用外网地址。

2. 控制消息推送

在媒体服务器编辑页可配置：

配置项	说明
启用消息推送	总开关。关闭后不发消息，但 Webhook 仍会接收并处理业务
推送事件类型	可多选。不选或全选表示推送全部事件

也就是说：

接收 Webhook：始终生效，用于观影报告实时采集等业务
消息推送：可按服务器、按事件类型单独控制

3. 前置条件

若地址弹窗提示无法生成，请先处理：

提示	处理方式
尚未配置访问地址	系统设置中填写内网主机地址 / 外网访问地址
尚未启用 API Key	账户安全设置中创建并启用 API Key
当前类型不支持	仅 Emby / Jellyfin / Plex 支持媒体服务级 Webhook

地址中包含 API Key，请勿分享。停用或删除对应 Key 后，地址会立即失效。

📨 开放消息渠道 Webhook

系统提供了一个开放的 Webhook 接口，允许外部系统通过配置的消息渠道发送通知。

接口地址： /api/v1/message/openSend

请求方法： POST

请求头要求：

Content-Type: application/json
apiKey: 您的API密钥（获取方法请参考我的信息）不一定需要添加请求头，使用此接口需要API密钥认证，请参考统一的API鉴权文档了解详细信息。

请求体格式：

{
  "title": "消息标题",
  "content": "消息内容",
  "imageUrl": "https://example.com/image.jpg",
  "proxy": false
}

参数	类型	必填	说明
title	string	是	消息标题
content	string	是	消息内容
imageUrl	string	否	完整的图片地址（可选）
proxy	bool	否	是否需要代理（可选），开启后图片将转换为ms接口代理地址

📝 请求示例

使用 cUrl:

curl -X POST "http[s]://your-domain.com[:port]/api/v1/message/openSend" \
  -H "Content-Type: application/json" \
  -H "apiKey: your-api-key" \
  -d '{"title": "消息标题", "content": "消息内容"}'

使用 wget:

wget -qO- "http[s]://your-domain.com[:port]/api/v1/message/openSend" \
  --header="Content-Type: application/json" \
  --header="apiKey: your-api-key" \
  --post-data='{"title": "消息标题", "content": "消息内容"}'

使用 JavaScript fetch:

fetch('http[s]://your-domain.com[:port]/api/v1/message/openSend', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apiKey': 'your-api-key'
  },
  body: JSON.stringify({
    title: '消息标题',
    content: '消息内容'
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

🔐 安全说明

使用此接口需要API密钥认证，请参考统一的API鉴权文档了解详细信息。

⚠️ 注意事项

请确保API密钥的安全性，不要在公开场合泄露
发送的消息将通过系统中配置的消息渠道进行推送
可以在消息通知页面测试配置的消息渠道是否正常工作

🛠 常见应用配置示例

青龙面板

在青龙面板的配置文件中添加以下配置：

## 14. 自定义推送
export WEBHOOK_URL="http[s]://your-domain.com[:port]/api/v1/message/openSend"
export WEBHOOK_HEADERS="Content-Type:application/json"$'\n'"apiKey:your-api-key"
export WEBHOOK_BODY='title:$title
content:$content'
export WEBHOOK_METHOD="POST"
export WEBHOOK_CONTENT_TYPE="application/json"

其中：

your-domain.com[:port] 是您的Media Saber服务地址和端口
your-api-key 是您的API密钥

QD签到框架

在QD签到框架中，通过"工具箱-自定义推送"进行配置：

请求方法：POST
地址：http[s]://your-domain.com[:port]/api/v1/message/openSend
Header配置：
```
{
  "apiKey": "your-api-key"
}
```
类型：application/json

POST Data：

{
  "title": "{t}",
  "content": "{log}"
}

其中：

your-domain.com[:port] 是您的Media Saber服务地址和端口
your-api-key 是您的API密钥
{t} 和 {log} 是QD签到框架的内置占位符

Lucky

在Lucky的DDNS任务编辑中，通过Webhook启用进行配置：

接口地址：http[s]://your-domain.com[:port]/api/v1/message/openSend
请求头：
```
apiKey: sk-XXXX
```

请求体：

{"title":"🛜域名同步反馈","content":"IP地址：\n#{ipAddr} \n域名更新成功列表：\n#{successDomainsLine}\n域名更新失败列表：\n#{failedDomainsLine}\n同步触发时间: \n#{time}"}

接口调用成功包含的字符串：SUCCESS （或者禁用Webhook接口调用成功字符串检测）

填写完成后可点击 Webhook手动触发测试 按钮测试是否正确，最后点击修改任务保存修改。

其中：

your-domain.com[:port] 是您的Media Saber服务地址和端口
sk-XXXX 是您的API密钥

🎬 Emby/Webhook配置

1. 进入Webhook设置

打开Emby控制台，进入设置 → 服务器 → Webhook，点击添加Webhook：

2. 配置Webhook参数

填写以下信息：

名称：自定义Webhook名称
URL：优先使用 Media Saber「媒体服务器」页复制的地址；格式为
http[s]://your-domain.com[:port]/api/v1/webhook/mediaServer/{媒体服务ID}?apiKey=your-api-key
请求内容类型：选择application/json

🔑 推荐：在 Media Saber 的媒体服务器卡片/编辑页点 Webhook 地址，直接复制内网或外网完整地址。
也可参考 API鉴权文档手动拼接。

配置完成后可以点击发送测试Webhook验证配置：

3. 验证测试消息

配置成功后，Media Saber应该会收到一条测试信息：

4. 配置事件和用户

继续选择要触发通知的事件、用户和媒体库，按需选择您想监控的选项：

5. 完成配置

填写完所有信息后，点击添加Webhook完成配置：

6. 测试功能

此时在Emby中操作您刚刚勾选的事件时，Media Saber会收到相关信息通知：

🐙 Jellyfin Webhook配置

GitHub文档说明：https://github.com/jellyfin/jellyfin-plugin-webhook

1. 安装Webhook插件

打开Jellyfin控制台，进入插件 → 目录，找到Webhook插件并点击：

点击安装Webhook：

2. 重启Jellyfin服务

安装完成后会提示重启Jellyfin服务，按要求重启后状态显示active表示成功：

3. 配置Webhook

在插件设置中，填写以下信息：

Server Url：Jellyfin服务器URL
点击Add Generic Destination按钮新增一个Hook

配置以下参数：

Webhook Name：自定义Webhook名称
Webhook Url：优先使用 Media Saber「媒体服务器」页复制的地址；格式为
http[s]://your-domain.com[:port]/api/v1/webhook/mediaServer/{媒体服务ID}?apiKey=your-api-key
Notification Type：勾选你想触发通知的通知类型
User Filter：勾选你想触发通知的用户
Item Type：勾选你想监控的媒体类型
Send All Properties 和 Template：二选一即可，默认勾选Send All Properties (ignores template)
点击Add Request Header，新增一组请求头：
- Key: Content-Type
- Value: application/json