01
只处理必要信息
Forward 入库通知 Webhook 接收剧集标题、TMDB ID、季号、集号等字段，用于判断是否需要推送。
Forward Push · Webhook 接入
入库通知 Webhook
媒体服务器把新剧集入库事件发到 Forward，Forward 再按追剧日历、用户订阅、服务器绑定和系统通知权限过滤，命中后通过 APNs 送达 iPhone。
已支持 Emby 和 MoviePilot 的入库事件，也支持 webhook 连通性测试推送。
Media Server
online
POST
/v1/push/webhook/<token>
source = Emby / MoviePilot
tmdb = 12345 · S01E02
/v1/push/webhook/<token>
source = Emby / MoviePilot
tmdb = 12345 · S01E02
入库通知
第 1 季 第 2 集已入库。点击直接打开追剧详情。
追剧日历命中
服务器绑定已启用
APNsqueued
Service Statement
对外服务声明
Webhook 只接收触发通知所需的元数据，不读取媒体文件，也不接管你的媒体服务器。路径 token 是服务器身份凭证，需要妥善保管。
02
不是所有入库都推送
服务会先判断用户是否正在追踪该剧、是否绑定服务器、是否允许通知，以及事件是否能匹配到具体季集。
03
批量事件会被控制
整季回填和重复 webhook 会被合并、去重或限流，避免用户被无意义的入库通知刷屏。
PRV
请求来源不进入记录或统计
Forward 仅处理 webhook body 中用于识别剧集和触发推送的字段，不记录或统计请求来源，例如来源 IP、User-Agent 等。通知链路中的服务器口令、设备标识和用户绑定关系均按脱敏或哈希身份参与处理，对外日志、统计和诊断不暴露具体个人或设备身份。
Setup Flow
四步完成接入
服务端注册 webhook，用户端绑定推送口令；两边完成后，媒体服务器的入库事件才会进入 Forward 推送链路。
TG
注册服务器
在 Telegram 机器人 @forwardwebhookbot 注册你的媒体服务器，生成专属 webhook 地址。
URL
配置 Webhook
把机器人返回的 webhook 地址填到 Emby、MoviePilot 或你的自动化工具中。
APP
绑定口令
用户在 Forward 的「入库通知」中输入推送口令，并允许系统通知权限。
APN
命中推送
新剧集入库后，Forward 匹配追剧日历和订阅关系，命中后发送 APNs 通知。
Webhook Payload
Webhook 请求格式
已支持 Emby 和 MoviePilot 的入库事件格式。TMDB ID 是最稳定的匹配字段，标题只作为兜底。
API
请求地址
把机器人返回的完整地址配置到媒体服务器。
HTTPwebhook endpoint
POST https://<push-service-domain>/v1/push/webhook/<token> Content-Type: application/json
Item.Type
必须是 Episode，其他类型会跳过。
ProviderIds.Tmdb
推荐提供，用于准确匹配正在追的剧。
ParentIndexNumber
季号，例如第 1 季传 1。
IndexNumber
集号，例如第 2 集传 2。
已支持的来源
Emby 可直接发送
Item 结构；MoviePilot 的转移完成事件也已支持，服务会从媒体信息和元数据中提取 TMDB ID、季号和集号。
JSON
请求示例
下面是一个最小可识别的 Emby 风格剧集入库事件。
JSONEmby-style payload
{
"Event": "library.new",
"Item": {
"Type": "Episode",
"SeriesName": "Example Show",
"Name": "Episode Title",
"ProviderIds": {
"Tmdb": "12345"
},
"ParentIndexNumber": 1,
"IndexNumber": 2
}
}
测试推送
发送 webhook 测试事件时，Forward 会向绑定该推送口令的第一个已启用用户发送一条测试通知，用于确认 webhook 和 APNs 链路已经连通。
JSONtest payload
{
"Event": "system.webhooktest"
}
Diagnostics
返回结果怎么理解
Webhook 返回值是诊断信息。skipped 通常代表事件被正常接收但不满足推送条件，不等于媒体服务器配置失败。
已进入推送队列
事件命中追剧日历和设备订阅，服务已创建推送任务。
{ "queued": 123 }
正常跳过
常见原因包括非剧集、缺少字段、不在追剧日历、该季集不存在或重复事件。
{ "skipped": "missing-fields" }
需要处理
401 表示 token 无效；429 表示短时间请求过多，需要降低 webhook 触发频率。
{ "ok": false, "code": "rate_limited" }
FAQ
常见问题
如果 webhook 已收到但没有推送，先从跳过原因、用户绑定状态和系统通知权限三处排查。
为什么入库了但没有收到通知？
可能是用户没有追这部剧、没有绑定对应推送口令、关闭了系统通知、事件不是 Episode，或 payload 缺少 TMDB ID、季号、集号。
电影入库会推送吗？
当前对外口径只处理电视剧单集。电影、整季和其他聚合型事件会被跳过。
批量整理媒体库会不会刷屏？
同一服务器同一剧短时间内多集入库会合并进同一个任务，服务还会按服务器限流。
Webhook token 泄露怎么办？
重新生成 webhook 地址即可。新 token 生效后，旧 token 会失效，媒体服务器需要更新配置。
服务器只负责告知“入库了”
Forward 负责判断“该不该通知用户”。
这种分工能保留自建媒体服务器的自由度，同时避免把通知变成无差别广播。每一次推送，都要经过服务器身份、剧集识别、追剧日历、用户绑定和设备订阅的共同确认。