Webhook 通知

听悦可以在登录、播放、入库和扫描等事件发生时，主动向外部服务发送通知。每个 Webhook 都能独立设置请求头和 Body 模板，因此既能连接企业微信，也能连接自建的 ntfy、Gotify 或自动化服务。

按事件推送

每个目标可单独选择登录、播放、媒体库变更、作品变更和扫描完成事件。

请求头和 Body 都可以使用变量，JSON 模板还支持自动转义。

测试发送会展示 HTTP 状态、服务响应和最终请求体，排错更直接。

管理员进入 我的 - 设置与管理 - 通知与事件，点击“添加 Webhook”。填写名称和 URL 后，可以从常见模板中选择服务，也可以完全自行编辑。

企业微信 Markdown、企业微信文本、ntfy JSON、Gotify JSON、原始事件 JSON 和纯文本。

普通变量会原样输出，适合纯文本；JSON 请求体请使用{{json:变量}}，它会自动处理引号和换行。

{{title}}
{{message}}
{{event}}
{{notification}}
{{data.username}}

{
  "title": {{json:title}},
  "message": {{json:message}},
  "event": {{json:event}}
}

{{notification}} 是“标题 + 换行 + 正文”，{{json:payload}} 会输出完整原始事件。

URL 使用群机器人提供的完整地址，机器人密钥已经包含在 URL 的key参数中。

https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=机器人密钥

{
  "msgtype": "markdown",
  "markdown": {
    "content": {{json:notification}}
  }
}

听悦会继续检查企业微信响应里的 errcode，避免 HTTP 200 但消息实际发送失败。

JSON 发布模式填写服务根地址，Topic 写在请求体中。私有服务可增加Authorization请求头。

https://ntfy.example.com

{
  "topic": "ting-reader",
  "title": {{json:title}},
  "message": {{json:message}},
  "priority": 3,
  "tags": ["headphones"]
}

使用 Gotify Application Token，并将它放在消息接口 URL 中。

https://gotify.example.com/message?token=APPLICATION_TOKEN

{
  "title": {{json:title}},
  "message": {{json:message}},
  "priority": 5
}

请求头可用于 Bearer Token、Basic Auth 或目标服务的自定义参数。值同样支持模板变量。

Content-Type: application/json
Authorization: Bearer your-token
X-Event: {{event}}

认证 Token 会随请求发送。建议使用 HTTPS，并避免把完整 Token 发布到日志或截图中。

user.login

用户登录成功时触发。

playback.play

用户开始播放作品或章节时触发。

library.scan_completed

媒体库扫描任务结束时触发。

book.created

新作品被创建或扫描入库时触发。