GitHub webhook 本地测试让你无需部署到 staging，就能在自己的机器上接收 push、pull request、issue 和 workflow 事件。运行一个 localhost 隧道，在你的 GitHub App 或仓库设置中注册 HTTPS URL，便可在完整签名验证下调试处理器。
为什么 GitHub webhook 需要公网端点
GitHub 将 webhook 事件作为 HTTP POST 请求投递到一个配置好的 URL。你在 127.0.0.1 的本地机器对 GitHub 的服务器不可达。localhost 隧道提供 GitHub 所需的公网 HTTPS 端点。
GitHub Apps 与仓库 webhook
仓库 webhook
在 Settings → Webhooks 中按仓库配置。适合在功能开发期间测试单个仓库的事件处理器。
GitHub App webhook
在你的 GitHub App 设置中按应用级别配置。当构建服务多个仓库或组织的集成时需要它。
两种投递方式都通过 X-Hub-Signature-256 头使用 HMAC-SHA256 签名验证。
分步：GitHub webhook 本地测试
- 启动带 webhook 端点的本地应用（例如
/api/webhooks/github）。 - 运行
npx portpreview 3000获取公网 HTTPS URL。 - 在 GitHub 中，把隧道 URL 加上你的 webhook 路径作为 payload URL。
- 把 content type 设为
application/json，并选择要接收的事件。 - 生成一个 webhook secret，存进本地环境变量。
- 触发事件（push 一个提交、开一个 PR、建一个 issue）并检查投递。
- 确认你的处理器验证签名并在 10 秒内返回 2xx 响应。
在本地验证 GitHub webhook 签名
GitHub 用你的 webhook secret 给每个载荷签名。你的处理器必须：
- 在 JSON 解析前读取原始请求体。
- 用你的 secret 计算 HMAC-SHA256。
- 用常量时间比较与
X-Hub-Signature-256头比对。
保留原始头部的隧道工具让你测试真实的验证路径。本地开发中切勿跳过签名检查。
本地要测试的事件
push— CI 触发逻辑、分支保护钩子、部署流水线。pull_request— 评审自动化、标签机器人、合并检查。issues— issue 追踪同步、指派工作流。installation— GitHub App 安装/卸载生命周期。workflow_run— CI 后自动化与产物处理。
调试失败的 GitHub webhook 投递
GitHub 以指数退避重试失败投递。本地测试常见失败：
- 处理器超时（GitHub 期望 10 秒内响应）。
- 在验证前解析请求体导致签名不匹配。
- GitHub 重试时隧道会话已过期。
- 事件过滤器错误——处理器收到它不处理的事件。
用 webhook 重放重新测试失败投递，无需 push 新提交。
GitHub webhook 测试 vs smee.io
smee.io 是本地开发中流行的 GitHub webhook 代理。它在基础转发上很好用，但缺少内置的请求检查和重放。PortPreview 在一个工具里把隧道与捕获、重放结合起来。更广泛的 webhook 调试指南见如何在本地调试 webhook。
加入 PortPreview 等候名单，获得带内置请求可见性的 GitHub webhook 测试。