如何使用Python监控GitHub仓库的新Issue_通过GitHub-API实时回调

GitHub Webhook比轮询更可靠，因其避免漏事件、节省资源且符合API规范；Webhook由仓库主动推送，只要服务返回200 OK即可实时接收Issue事件。

GitHub Webhook 为什么比轮询更可靠

选择GitHub Webhook（事件回调）来替代定时轮询/issues API，背后有几个硬核理由。最直接的，它能有效避免事件遗漏，同时节省服务器资源。更重要的是，这符合GitHub官方的“游戏规则”——平台明确要求高频轮询必须配合缓存和节流机制，否则一旦触发X-RateLimit-Remaining耗尽，等待你的就是403 Forbidden。而Webhook的机制则完全不同，它是由仓库主动向你“喊话”，只要你的服务端能稳稳地回应一个200 OK，Issue创建的瞬间，通知就能送达。

不过，这里有个关键前提：Webhook默认只向公网可访问的URL推送。如果你在本地开发调试，就需要借助ngrok或localtunnel这类工具将本地端口暴露到公网。否则，在GitHub后台配置时，就会看到那个令人头疼的提示：“Unable to deliver payload”。

如何用 Flask 快速接收并解析 Issue webhook

想要快速搭建一个能接收Webhook的服务，Flask是个轻量又高效的选择。几行代码就能拉起一个端点，但真正的核心，其实不在于“怎么写路由”，而在于“如何验证身份”。GitHub会在X-Hub-Signature-256这个请求头里放置一个HMAC-SHA256签名，你必须用自己预设的webhook secret重新计算并比对。这一步如果省略，任何伪造的请求都能长驱直入，触发你的业务逻辑，安全隐患可不小。

• 首先，通过request.headers.get(“X-Hub-Signature-256”)获取签名，其格式为sha256=xxx。
• 接着，用hmac.new(secret.encode(), request.get_data(), digestmod=hashlib.sha256).hexdigest()计算出你期望的签名值。
• 比对时，务必使用hmac.compare_digest()方法，它能安全地抵抗时序攻击。
• 最后，解析request.json时，要确认action == “opened”才是新创建的Issue，可别把edited或reopened这类更新事件也误判了。

from flask import Flask, request
import hmac, hashlib

app = Flask(__name__)
SECRET = “your_webhook_secret_here”

@app.route(“/webhook”, methods=[“POST”])
def handle_webhook():
    sig = request.headers.get(“X-Hub-Signature-256”)
    if not sig or not sig.startswith(“sha256=”):
        return “Bad signature”, 400

    expected = hmac.new(SECRET.encode(), request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig[7:], expected):
        return “Invalid signature”, 401

    payload = request.json
    if payload.get(“action”) == “opened” and payload.get(“issue”):
        print(“New issue:”, payload[“issue”][“html_url”])
    return “”, 200

Webhook 配置里最容易填错的三个字段

进入仓库的 Settings → Webhooks → Add webhook 页面，有三个字段堪称“魔鬼细节”，填错任何一个，事件都可能石沉大海。

立即学习“Python免费学习笔记（深入）”；

• Payload URL：这里必须填写完整的HTTPS地址（即使你用的是ngrok生成的临时域名），不能包含路径参数。例如https://abc123.ngrok.io/webhook，结尾切记不要多加?或#。
• Which events would you like to trigger this webhook?：这里记得勾选Issues事件。一个常见的失误是只勾了Pushes，或者选择了Let me select individual events却漏掉了Issues。
• Secret：此处填写的密钥，必须和代码中定义的SECRET变量完全一致，区分大小写，且不能有多余空格。复制粘贴时尤其要小心，避免带入不可见的Unicode字符。

点击Add webhook之后，别急着离开。立刻点击右侧的Recent Deliveries，查看第一条测试事件的响应状态码和响应体。如果显示Connection timed out，通常意味着你的后端服务没有启动，或者域名无法被公网访问；如果显示401 Unauthorized，那十有八九是Secret密钥不匹配。

收到 Issue 后该做什么才不算白接

仅仅在控制台打印出Issue信息，那只是验证了通信链路。要构建一个真正可用的监控流程，至少得做好三件事：去重、归档和通知。首先，GitHub可能因为网络问题重复发送同一事件（每个事件都有唯一的X-GitHub-Delivery头标识），所以不能只依赖issue.number去重——同一个Issue可能被关闭后又重新打开，从而触发多次opened动作。

• 建议使用(repository.full_name, issue.number, action)这样的三元组作为唯一键，存入Redis或SQLite，从根本上避免重复处理。
• 接下来，从事件负载中提取关键信息，如issue.title（标题）、issue.user.login（创建者）、issue.created_at（创建时间）和issue.labels（标签），根据需求存入数据库或写入日志文件。
• 最后是通知环节。切忌在代码里硬编码邮件或钉钉的发送逻辑。更优雅的做法是通过环境变量（例如NOTIFY_CHANNEL=dingtalk）来控制通知渠道，然后调用相应的SDK。这样，未来切换或扩展通知方式时，就无需改动核心代码了。

需要牢记的是，Webhook采用的是“尽力投递”模式，它不保证100%送达，也不保证事件顺序。如果你的业务逻辑对事件丢失零容忍，那么最好配合一个定期的补漏机制：例如，每天执行一次GET /repos/{owner}/{repo}/issues?state=all&sort=created&direction=desc&per_page=100这样的API调用，将结果与本地记录的最新created_at时间戳进行比对，查缺补漏。