{"id":29471243,"url":"https://github.com/hxsyzl/webhook-notifier","last_synced_at":"2025-07-14T13:33:43.766Z","repository":{"id":303372187,"uuid":"1014763404","full_name":"hxsyzl/WebHook-Notifier","owner":"hxsyzl","description":"一个灵活、自托管的通知服务，用于接收来自 GitHub / GitLab / Gitea 的 Git 推送事件和 RSS 订阅更新，然后将消息分发到 Telegram、电子邮件和 QQ 等多个平台","archived":false,"fork":false,"pushed_at":"2025-07-07T08:32:19.000Z","size":128,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-07T09:38:18.898Z","etag":null,"topics":["email","onebot","telegram","webhook"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hxsyzl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-06T11:19:23.000Z","updated_at":"2025-07-07T08:35:02.000Z","dependencies_parsed_at":"2025-07-07T09:38:39.064Z","dependency_job_id":"4f0f3bc2-faf2-49aa-8b76-37b981d151aa","html_url":"https://github.com/hxsyzl/WebHook-Notifier","commit_stats":null,"previous_names":["hxsyzl/webhook-notifier"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hxsyzl/WebHook-Notifier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hxsyzl%2FWebHook-Notifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hxsyzl%2FWebHook-Notifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hxsyzl%2FWebHook-Notifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hxsyzl%2FWebHook-Notifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hxsyzl","download_url":"https://codeload.github.com/hxsyzl/WebHook-Notifier/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hxsyzl%2FWebHook-Notifier/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265297455,"owners_count":23742586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","onebot","telegram","webhook"],"created_at":"2025-07-14T13:30:49.669Z","updated_at":"2025-07-14T13:33:43.758Z","avatar_url":"https://github.com/hxsyzl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebHook Notifier\n\n[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)\n\n一个灵活、自托管的通知服务，用于接收来自 **GitHub / GitLab / Gitea** 的 Git 推送事件和 **RSS 订阅**更新，然后将格式化的消息分发到 **Telegram、电子邮件和 QQ** 等多个平台。\n\n---\n\n## 核心功能\n\n- **多平台 Git 支持**：原生支持来自 GitHub、GitLab 和 Gitea 的 `push` 事件 WebHook。\n- **全面的 RSS 监控**：\n    - **定时轮询**：可配置间隔时间，自动检查 RSS 源的更新。\n    - **WebHook 接入**：提供 `/webhook/rss` 端点，支持 RSS to WebHook 服务（如 rss-to-webhook.com）的实时推送。\n- **多渠道通知**：\n    - \n    - Telegram Bot\n    - 电子邮件 (SMTP)\n    - Napcat (QQ Bot)\n- **安全可靠**：\n    - **签名验证**：验证来自 GitHub (sha1/sha256) 和 Gitea (sha256) 的 WebHook 签名，确保请求来源可信。\n    - **Token 验证**：支持 GitLab 的 `X-Gitlab-Token` 验证。\n    - **RSS 去重**：自动记录已推送的文章，防止因源更新导致的重复通知。\n- **高度可配置**：\n    - **集中配置**：所有功能均通过一个 `config.yaml` 文件进行管理。\n    - **通知延迟**：可设置一个全局延迟，在接收到事件后等待一段时间再发送通知。\n    - **代理支持**：支持为所有出站 HTTP 请求（Telegram, Napcat, RSS抓取）配置代理。\n\n## 工作流程\n\n```\n            +---------------------------+\n Git Push   |                           |   +------------------+\n (GitHub,   |                           |   |                  |\n GitLab,    +---\u003e Git \u0026 RSS WebHook     +---\u003e Telegram         |\n Gitea)     |        Notifier           |   |                  |\n            |                           |   +------------------+\n RSS Update |                           |\n (Polling/  |                           |   +------------------+\n  Webhook)  +---\u003e (Configurable Delay)  +---\u003e Email (SMTP)     |\n            |                           |   |                  |\n            |                           |   +------------------+\n            |                           |\n            |                           |   +------------------+\n            |                           |   |                  |\n            +---------------------------+   +---\u003e QQ           |\n                                            |                  |\n                                            +------------------+\n```\n\n## 安装与启动\n\n#### 1. 克隆仓库\n\n```bash\ngit clone https://github.com/hxsyzl/WebHook-Notifier.git\ncd WebHook-Notifier\n```\n\n#### 2. 安装依赖\n\n项目依赖于以下 Python 包。强烈建议在虚拟环境中使用 `pip` 进行安装，以避免与系统级的 Python 包产生冲突。\n\n##### 2.1. 创建并激活虚拟环境\n\n在项目根目录下，根据你的操作系统执行以下命令：\n\n**Windows:**\n\n```bash\n# 创建名为 venv 的虚拟环境\npython -m venv venv\n# 激活虚拟环境\n.\\venv\\Scripts\\activate\n```\n\n**macOS / Linux:**\n\n```bash\n# 创建名为 venv 的虚拟环境\npython3 -m venv venv\n# 激活虚拟环境\nsource venv/bin/activate\n```\n\n成功激活后，你的命令行提示符前通常会显示 `(venv)` 字样。\n\n##### 2.2. 安装依赖包\n\n```\n# requirements.txt\nfastapi\nuvicorn[standard]\nPyYAML\nhttpx\nfeedparser\n```\n\n```bash\npip install -r requirements.txt\n```\n\n#### 3. 编辑配置文件\n\n根据你的需求进行配置文件模板修改。\n\n```bash\nnano config.yaml\n```\n\n详细的配置说明请参见下一章节。\n\n#### 4. 启动服务\n\n使用 `uvicorn` 启动应用。\n\n```bash\n# 在开发环境中，使用 --reload 参数可以在代码变更后自动重启服务\nuvicorn main:app --host 0.0.0.0 --port 8000 --reload\n\n# 在生产环境中，建议不使用 --reload\nuvicorn main:app --host 0.0.0.0 --port 8000\n```\n\n服务启动后，你可以在 `http://\u003cyour-server-ip\u003e:8000` 看到欢迎信息。\n\n欢迎信息类似于：{\"message\":\"WebHook Notifier 服务正在运行\",\"version\":\"1.1.0\",\"endpoints\":{\"git_webhook\":\"/webhook/git\",\"rss_webhook\":\"/webhook/rss\"}}\n\n\n## 效果展示\n![alt demo](accept.png)\n![alt demo-1](push-tg.png)\n## 配置 (`config.yaml`)\n\n这是所有配置的核心。以下是一个包含所有可用选项的示例：\n\n```yaml\n# 全局设置\nglobal:\n  # 接收到事件后，延迟多少秒再发送通知。设为 0 表示立即发送。\n  notification_delay_seconds: 5\n  # 代理设置 (适用于 Telegram, Napcat, RSS抓取)\n  proxy:\n    enabled: false\n    # 代理地址，例如 http://127.0.0.1:7890 或 socks5://127.0.0.1:1080\n    url: \"http://127.0.0.1:7890\"\n\n# Git 平台设置\ngithub:\n  # 在 GitHub WebHook 设置中填写的 Secret\n  secret: \"your_github_webhook_secret\"\n\ngitlab:\n  # 在 GitLab WebHook 设置中填写的 Secret Token\n  secret: \"your_gitlab_webhook_secret\"\n\ngitea:\n  # 在 Gitea WebHook 设置中填写的 Secret\n  secret: \"your_gitea_webhook_secret\"\n\n# RSS 订阅设置\nrss:\n  enabled: true\n  # 自动检查 RSS 更新的间隔时间（分钟）\n  check_interval_minutes: 30\n  # RSS WebHook 设置\n  webhook:\n    # 用于验证 RSS to WebHook 服务请求的 Secret (可选)\n    secret: \"your_rss_webhook_secret\"\n  # 要监控的 RSS 源列表\n  feeds:\n    - name: \"Awesome RSS\"\n      url: \"https://example.com/feed.xml\"\n      enabled: true\n    - name: \"Another Feed\"\n      url: \"https://another.com/rss\"\n      enabled: true\n\n# 通知渠道设置\ntelegram:\n  enabled: true\n  bot_token: \"123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11\"\n  chat_id: \"-1001234567890\" # 或个人用户的 chat_id\n\nemail:\n  enabled: false\n  smtp_server: \"smtp.example.com\"\n  smtp_port: 587\n  smtp_username: \"user@example.com\"\n  smtp_password: \"your_email_password_or_app_token\"\n  sender_email: \"notifier@example.com\"\n  recipient_emails:\n    - \"recipient1@example.com\"\n    - \"recipient2@example.com\"\n  # 如果 SMTP 端口是 465，通常需要将 use_ssl 设为 true\n  use_ssl: false\n  # 如果 SMTP 端口是 587，通常需要将 use_tls 设为 true\n  use_tls: true\n\nnapcat:\n  enabled: false\n  # Napcat HTTP API 的基础 URL\n  base_url: \"http://127.0.0.1:3001\"\n  # 发送模式: private (私聊), group (群聊), all (两者都发)\n  send_mode: \"all\"\n  # 私聊 QQ 号\n  user_id: \"10001\"\n  # 群聊群号\n  group_id: \"123456789\"\n```\n\n## 使用方法\n\n### 1. 配置 Git WebHook\n\n在你的 GitHub/GitLab/Gitea 仓库设置中，添加一个新的 WebHook：\n\n- **Payload URL / 目标 URL**: `http://\u003cyour-server-ip\u003e:8000/webhook/git`\n- **Content Type / 内容类型**: `application/json` (推荐) 或 `application/x-www-form-urlencoded`\n- **Secret / 密钥**: 填写你在 `config.yaml` 中为对应平台设置的 `secret`。\n- **Events / 触发事件**: 选择 `push` 或 \"推送事件\"。\n\n### 2. 配置 RSS\n\n#### 方式一：自动轮询 (推荐)\n\n只需在 `config.yaml` 的 `rss.feeds` 列表中添加你想要监控的 RSS 地址，并确保 `rss.enabled` 为 `true`。服务启动后会自动按 `check_interval_minutes` 定义的周期进行检查。\n\n#### 方式二：使用 WebHook\n\n如果你希望获得更实时的 RSS 更新，可以使用 rss-to-webhook 或类似的第三方服务。\n\n- **Webhook URL**: `http://\u003cyour-server-ip\u003e:8000/webhook/rss`\n- 在第三方服务中配置你的 RSS 源，并将其指向以上 URL。\n- （可选）如果第三方服务支持，可以配置一个 `secret` 并填入 `config.yaml` 的 `rss.webhook.secret` 中以增加安全性。\n\n## API 端点\n\n- `GET /`\n  - 返回服务的运行状态和版本信息。\n- `POST /webhook/git`\n  - 接收来自 Git 平台的 WebHook 请求。\n- `POST /webhook/rss`\n  - 接收来自 RSS to WebHook 服务的请求。\n\n## 数据持久化\n\n服务会在应用根目录创建一个 `rss_last_check.json` 文件，用于存储已见过的 RSS 文章ID，以防止重复通知。请确保应用对此文件有读写权限。该文件会在服务正常关闭时自动保存。","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhxsyzl%2Fwebhook-notifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhxsyzl%2Fwebhook-notifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhxsyzl%2Fwebhook-notifier/lists"}