Gopeed 如何配置 Webhook 在任务完成或失败时通知外部服务并验证连通性?
Gopeed 如何配置 Webhook 在任务完成或失败时通知外部服务并验证连通性?
如果你在用 Gopeed(基于 Go 和 Flutter 的下载管理器)批量管理任务,又希望在任务下载完成或失败时自动通知外部服务(内部系统、CI、告警渠道等),就需要配置它的 Webhook 功能。完成本文操作后,Gopeed 会在任务结束(成功或失败)时向指定地址推送一条 JSON 事件,并且你可以在不发起真实下载的情况下,通过内置的测试接口先验证这个地址的连通性。
Webhook 的发送逻辑位于 pkg/download/webhook.go,触发点在 pkg/download/downloader.go(完成)和 pkg/download/downloader.go(失败)。
准备条件
- 一个正在运行的 Gopeed 实例,并且其 REST API 可访问。如果走界面配置,直接使用 Gopeed 客户端即可;如果走接口配置,需要知道 REST API 的地址和端口。仓库中的本地开发入口 cmd/api/main.go 启动的 API 地址为
127.0.0.1:9999,本文接口示例均按此地址书写,其他环境请替换为你实际的 API 地址。 - 一个可被 Gopeed 访问到的接收端点。该端点必须返回 HTTP 200,连通性测试才算通过。
配置 Webhook:开关与 URL 列表
Webhook 配置项定义在 pkg/base/model.go 的 WebhookConfig 中,结构为:
{
"webhook": {
"enable": true,
"urls": ["https://your-server.example.com/hooks/gopeed"]
}
}
enable:总开关,必须为true才会发送。urls:接收地址列表,支持配置多个,每个任务事件会推送到所有地址。列表中的空字符串会被忽略。https://your-server.example.com/hooks/gopeed是占位地址,替换为你自己的接收端点 URL,这是整篇文章中唯一需要你提供值的占位符。
另外,代码保留了向后兼容:如果配置里使用旧的 extra.webhookUrls 字段存放地址列表,同样会被识别(见 pkg/download/webhook.go)。新配置建议直接使用上面的 webhook 结构。
方式一:通过客户端设置界面
在 Gopeed 的设置页面中,Webhook 有两个入口(见 settings_page.dart):
- 打开 “Webhook” 开关(对应
webhook.enable); - 在推送地址列表中逐条添加、编辑或删除 URL(对应
webhook.urls); - 每条地址旁边提供测试按钮,点击即调用下文的连通性测试接口。
方式二:通过 REST API 修改配置
如果不用界面,可以通过配置接口读写同一份数据。先读取当前完整配置,只修改 webhook 部分后再整体写回(接口接受并保存完整的下载器配置结构,见 pkg/rest/api.go):
# 读取当前配置
curl http://127.0.0.1:9999/api/v1/config
# 将上一步返回的配置改为 webhook.enable=true、webhook.urls 填入你的地址后写回
curl -X PUT http://127.0.0.1:9999/api/v1/config \
-H "Content-Type: application/json" \
-d @config.json
PUT 成功后响应 code 为 0;写回失败时 code 为 1000,msg 中是错误信息。响应包装结构为 code / msg / data(见 pkg/rest/model/result.go)。
Gopeed 是如何推送的
了解推送行为,才能正确设计接收端。依据 pkg/download/webhook.go:
- 推送方式是 HTTP POST,请求头为
Content-Type: application/json和User-Agent: Gopeed-Webhook/1.0; - 请求体结构如下(
time为毫秒级 Unix 时间戳,payload.task为任务对象):
{
"event": "DOWNLOAD_DONE",
"time": 1700000000000,
"payload": { "task": { }
}
}
上面数值仅表示结构,event 实际只会取 DOWNLOAD_DONE(任务完成)或 DOWNLOAD_ERROR(任务失败)两个值。
- 每个 URL 的超时时间为 10 秒;
- 推送在后台异步进行,不会阻塞下载流程;
- 返回状态码在 200–299 区间记为发送成功;返回其他状态码时记录
webhook: received non-success status警告日志;请求本身失败(连不通等)记录webhook: failed to send request警告日志。
验证连通性:使用测试接口
正式跑任务前,先用内置测试接口确认地址可达。接口定义在 pkg/api/service.go,请求体只有一个 url 字段(见 pkg/rest/model/webhook.go):
curl -X POST http://127.0.0.1:9999/api/v1/webhook/test \
-H "Content-Type: application/json" \
-d '{"url": "https://your-server.example.com/hooks/gopeed"}'
判定方式:
- 成功:响应
code为0,data为空。此时你的接收端应能收到一条测试推送。 - 失败:响应
code为1000,msg形如webhook test failed: <url> returned status <状态码>。
两点需要注意:
- 测试要求接收端精确返回 HTTP 200。而真实任务推送的判定是 2xx 均算成功。如果接收端返回 201/204,测试接口会报失败,但真实事件仍然会被计为发送成功。
- 测试推送的是模拟任务而非真实任务数据:
TestWebhookUrl会构造一个事件类型为DOWNLOAD_DONE的模拟载荷,其中文件名为test-file.zip、大小 100MB(见 pkg/download/webhook.go)。这是文档代码中的固定示例值,只用于连通性验证,接收端不应据此做任何业务判断。
仓库测试 pkg/rest/server_test.go 覆盖了这条链路的验证方式:模拟接收端断言收到的 Content-Type 为 application/json、请求体包含 event、time、payload 三个字段;不可达的地址和非 200 响应均会走失败分支。
用真实任务做最终确认
连通性通过后,发起一次真实下载即可确认完整链路:
- 让一个任务正常下载完成,接收端应收到
event为DOWNLOAD_DONE的推送; - 让一个任务失败(例如无效地址),接收端应收到
event为DOWNLOAD_ERROR的推送; - 检查
payload.task内容与你发起的任务一致。
如果接收端没有收到推送,按代码行为依次核对:
- 配置中
webhook.enable是否为true且urls非空——两者任一不满足时getWebhookUrls返回空,根本不会发送; - 接收端是否在 10 秒内响应;
- Gopeed 日志中是否出现
webhook: received non-success status(地址可达但状态码非 2xx)或webhook: failed to send request(请求失败,通常是网络不可达)。
限制说明
- 推送是“尽力而为”:发送失败只记录警告日志,不会重试,也不会影响下载任务本身的状态;
- 测试接口每次只测一个 URL,且只接受返回 200 的地址;
- 配置修改通过
PUT /api/v1/config写回的是完整配置结构,写回前建议先用GET /api/v1/config拿到当前值再改动,避免覆盖其他配置段。