Webhook

xylplm2025/12/12大约 6 分钟使用文档其它

🪝 Webhook

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

🎯 支持的Webhook类型

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

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

📨 开放消息渠道 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：http[s]://your-domain.com[:port]/api/v1/webhook/emby?apiKey=your-api-key
请求内容类型：选择application/json

🔑 API Key配置：请参考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：http[s]://your-domain.com[:port]/api/v1/webhook/emby?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