FluxDown Webhook — 任务事件推送到任意端点

Webhook 是什么

FluxDown 的 Webhook 功能让你可以把任务生命周期事件实时推送到自己的 endpoint（HTTP(S) 地址）——不管这个 endpoint 是 Slack 机器人、飞书、一个自建的日志收集服务、还是另一个自动化流程（比如 n8n / Zapier / Home Assistant）。

怎么配

在「设置 → 自动化 → Webhook」里添加一条：

字段	说明
URL	你的 endpoint，比如 `https://hooks.slack.com/services/xxx`
Secret	可选，FluxDown 用它签名 payload（HMAC-SHA256）
队列过滤	只推送哪个队列的事件（不填 = 所有队列）
事件类型	勾选要推送哪些事件（见下）
自定义 Header	可选，POST 时带上的 header（比如 `Authorization: Bearer xxx`）

保存后，每次匹配到事件，FluxDown 就 POST 一份 JSON 到你的 URL。

事件类型

事件	什么时候触发
`task.started`	任务开始下载
`task.completed`	任务成功完成
`task.failed`	任务失败（附错误原因）
`task.paused`	任务被暂停
`task.resumed`	任务恢复
`task.removed`	任务被删除
`queue.started` / `queue.paused`	整个队列启停

Payload 格式

{
  "event": "task.completed",
  "timestamp": 1730000000,
  "task": {
    "id": "t-abc123",
    "url": "https://example.com/file.zip",
    "queue": "main",
    "protocol": "http",
    "status": "completed",
    "file_name": "file.zip",
    "file_size": 524288000,
    "duration_seconds": 245,
    "avg_speed": 2140000
  }
}

所有字段都有，你的 endpoint 可以按需取用。

典型场景

Slack / 飞书通知

配置 Slack Incoming Webhook 或飞书自定义机器人 Webhook，加事件过滤 task.completed 和 task.failed——重要文件下载完或失败时自动发到群里。

Home Assistant 自动化

NAS 上 FluxDown 下完一个 ISO → Webhook 推到 Home Assistant → Home Assistant 自动触发「自动挂载 ISO 到虚拟机」流程。

日志收集

所有任务事件推到自建日志服务（ELK / Loki / 自建 API），方便统计分析下载行为。

告警

task.failed 事件推到告警系统（PagerDuty / 飞书告警群）——稀有电驴资源下了几天终于失败时通知你。

重试与签名

重试 — endpoint 不可达或返回非 2xx，FluxDown 会指数退避重试（最多 5 次：1s → 2s → 4s → 8s → 16s）。
签名 — 填了 Secret 后，FluxDown 在 POST header 里加 X-FluxDown-Signature（HMAC-SHA256），你的 endpoint 可以验签防止伪造。
限流 — 同一个 endpoint 每秒最多 10 条，超过的事件丢掉（Webhook 是尽力推送，不是可靠队列）。

和 Hook 插件的区别

Webhook 适合出 FluxDown 之外的自动化（通知外部系统、推到云服务），Hook 插件适合留在 FluxDown 之内的自动化（完成后自动整理目录、自动上传下一个任务）。两者可以同时用——Hook 处理内部、Webhook 推出去。