GitHub webhook「停投」最常见的原因是目标 URL 错误、不可达，或返回了非 2xx HTTP 状态。在改任何应用代码之前，先打开仓库 webhook 设置里的 Recent Deliveries，看 GitHub 实际发了什么、收到了什么响应——十有八九答案就在那里。本文按结构化调试流程帮你分层定位故障、修复根因，让投递恢复，少靠猜。
三层调试模型
Webhook 投递是一条链上的三个环节。先判断哪一段断了，修复最快。若还没确认请求是否到达就去调处理器代码，可能白白花几小时追一个根本不在代码里的问题。
第一层 —— GitHub 是否真的发出？
GitHub 会记录每次投递尝试。在仓库（或组织）中进入 Settings > Webhooks > Recent Deliveries。每条记录包含端点返回的 HTTP 状态、完整请求负载与响应体。若你期待的事件下列表为空，可能是 webhook 被禁用、事件订阅配错，或极少数情况下平台延迟。
第二层 —— 公网端点是否收到？
若 GitHub 显示有投递，但应用侧毫无记录，问题在 GitHub 与你的服务器之间。类似 HookNexus 的 webhook 调试器 提供独立捕获点：GitHub 发到 HookNexus URL，你可在控制台确认是否收到，而不依赖自有服务是否健康。这是区分网络/基础设施问题与应用层 bug 最有效的方式。
第三层 —— 本地处理器是否执行？
确认请求到达公网端点后，剩余可能都在本地：转发隧道挂了、应用抛异常、或中间件（认证、签名验证）在处理器运行前就拒绝了请求。查应用日志，并参阅转发相关说明。
最常见原因
下面六种情况覆盖了绝大多数「webhook 没投递」报告。请按顺序排查，每一步都建立在前一步已排除的前提下。
1. Webhook URL 错误或过期
这是头号原因。常见于从开发环境复制 URL、轮换 HookNexus 端点后未更新 GitHub、或换域名未同步配置。打开仓库 webhook 配置，将 Payload URL 与端点实际监听的 URL 逐字符对比。特别注意末尾斜杠、协议（https 与 http）、端口号与路径段。
若使用 HookNexus，正确 URL 格式为：
https://api.hooknexus.com/h/<your-endpoint-id>
任何偏差——缺少 /h/ 前缀、旧端点 ID、域名拼写错误——都会让请求投进虚空。
2. 端点返回非 2xx 状态码
GitHub 将 200–299 之外的响应视为失败。常见情况包括：
- 301/302 重定向 —— GitHub 在 webhook 投递时不会跟随重定向。
- 401/403 —— 认证中间件在处理器看到请求前就拒绝。
- 404 —— 目标服务器上不存在该路由。
- 500 —— 处理器抛出未捕获异常。
健康的 webhook 处理器应尽快返回 200 OK，最好在完成任何重活之前。慢活应丢进后台队列。下面是一个正确的极简 Express 示例：
app.post("/webhooks/github", (req, res) => {
// Respond immediately so GitHub sees a 200
res.status(200).json({ received: true });
// Process asynchronously
setImmediate(() => {
handleGitHubEvent(req.body).catch((err) => {
console.error("Webhook processing failed:", err);
});
});
});
3. GitHub 在投，但你的端点没「接住」
有时 GitHub 的 Recent Deliveries 显示 200，应用却没有任何事件记录。通常表示上游代你确认了请求——例如负载均衡健康检查路由、CDN 边缘函数、或返回 200 却不转发 body 的兜底中间件。要确认这个 200 真的来自你的处理器，而不是前面的基础设施。
4. 密钥不一致导致拒绝
若在 GitHub 配置了 webhook 密钥，每次投递都会带 X-Hub-Signature-256 头。应用必须用同一密钥对原始请求体计算 HMAC-SHA256 并与该头比较。不一致可能来自只在一侧轮换密钥，或中间件在验证代码读到原始字节之前就解析了 body。完整步骤见 验证 GitHub Webhook 签名。
5. Localhost 转发断裂
若在本地开发并依赖隧道（HookNexus CLI、ngrok 等）把公网 URL 转到 localhost，故障点包括：
- 隧道进程未运行或重启后 URL 变了。
- 本地服务未在预期端口监听。
- 防火墙或 VPN 阻断隧道连接。
- 隧道 URL 过期（免费 ngrok 常见）。
在隧道终止的那台机器上做一次连通性测试：
curl -X POST http://localhost:3000/webhooks/github \
-H "Content-Type: application/json" \
-d '{"test": true}'
若连接错误，说明本地服务没在听；若非 200，问题在处理器而非隧道。
6. 未订阅需要的事件类型
GitHub webhook 可按事件配置。若只订阅了 push，而你的流程依赖 pull_request 或 issues，相关负载永远不会来。打开 webhook 配置，在 Which events would you like to trigger this webhook? 下确认集成所需的每一种事件都已勾选。
分步故障排查流程
Webhook 异常时按此顺序操作。每一步要么证明该层健康，要么直接暴露故障点。
第一步 —— 查看 GitHub Recent Deliveries
进入 GitHub 仓库，点击 Settings > Webhooks，选中对应 webhook，打开 Recent Deliveries。看最近几条：
- 若完全没有投递，确认 webhook 为启用状态，且触发事件确实发生过。
- 若有投递，记下 HTTP 状态。
200表示 GitHub 认为成功；其他状态都是线索。 - 点进某次投递可查看完整请求头、负载与端点返回的响应。
第二步 —— 确认端点 URL 正确
将 GitHub 中的 Payload URL 与实际提供服务的 URL 对比。若用 HookNexus，打开 控制台 确认端点 ID 一致。
第三步 —— 独立测试端点
从终端手动向 webhook URL 发请求，排除 GitHub 特有问题：
curl -i -X POST https://api.hooknexus.com/h/YOUR_ENDPOINT_ID \
-H "Content-Type: application/json" \
-H "X-GitHub-Event: ping" \
-d '{"zen": "Responsive is better than fast."}'
健康端点应返回 200。若 DNS 错误、连接超时或非 200，问题在 URL 或服务器，而非 GitHub。
第四步 —— 查看状态码与响应体
若 GitHub 显示 4xx 或 5xx，阅读 GitHub 记录的响应体，其中常有应用或基础设施返回的错误信息（如 “Unauthorized”、“Route not found”、“Internal Server Error”）。将错误与上文原因列表对应。
第五步 —— 核对事件订阅
仍在 webhook 设置中，确认集成需要的所有事件类型都已选中。常见错误是保留默认「仅 push」，而代码监听 pull_request、release 或 workflow_run。
第六步 —— 检查本地转发
若从公网端点转发到 localhost：
- 确认隧道或 CLI 进程在运行，且公网 URL 正确。
- 确认本地服务在正确端口监听。
- 直接向
localhost发测试请求（见上文原因 5 的 curl）。 - 查看应用日志中的入站请求与异常。
关于完整 GitHub webhook 调试 流程（含重放与负载检查），见专门指南。
用 HookNexus 隔离问题
「先捕获再转发」把投递拆成两段可观察流程，减少猜测。
第一步：让 GitHub 指向 HookNexus 端点。 在 HookNexus 控制台 创建端点，复制 URL 填入 GitHub webhook。此后每次来自 GitHub 的投递都会出现在控制台，含完整头、body 与时间——与本地代码无关。
第二步：检查捕获的请求。 若控制台能看到请求，说明 GitHub 侧正常；若看不到，再查 URL、事件订阅与 GitHub 自身投递日志。
第三步：转发到 localhost。 使用 HookNexus CLI 将捕获的请求转到本地开发机：
hooknexus listen <endpoint-id>
hooknexus forward <endpoint-id> --to http://localhost:3000/webhooks/github
这样可直接观察本地处理器收到什么。转发失败则问题在隧道或本地服务；转发成功但处理器报错则问题在应用。这种两步分离能最快定位根因。完整搭建见 HookNexus GitHub 集成文档。
快速检查清单
GitHub webhook 不投递时逐项核对，每项通常不到一分钟：
- Webhook 在 GitHub 设置中为 Active
- Payload URL 与线上一致（无拼写、协议与路径错误）
- 手动
curl测试时端点返回200 - GitHub 中的密钥与应用 HMAC 验证所用密钥一致
- 配置中已勾选所有需要的事件类型
- 若本地开发：本地服务在跑且转发隧道可用
- 没有中间件或代理在处理器之前拦截并返回非 200
常见问题
为什么 GitHub 显示 200，但应用没处理事件？
Recent Deliveries 里的 200 只表示该 URL 上有某处确认了请求，不一定是你的处理器——也可能是负载均衡探活、兜底路由或 CDN 边缘函数。查应用日志确认请求是否进入 webhook 处理器。若使用 HookNexus，对比控制台捕获的负载与应用日志。
GitHub 多久会把投递标为失败？
GitHub 对 webhook 投递有 10 秒超时。若端点在此时间内无响应，会记为超时失败并按策略重试。因此处理器应尽快返回 200，再异步处理负载。重的同步工作——写库、调外部 API、文件操作——应放到后台任务。
能否手动重试失败的 webhook 投递？
可以。在 Recent Deliveries 中点开某次投递，选择 Redeliver。GitHub 会用当前配置的 URL 发送相同负载（不是历史 URL）。若需要更灵活的重放（改请求头、换目标端点等），可使用 HookNexus 重放能力。
GitHub 会自动重试失败投递吗？
会。对非 2xx 或超时，GitHub 会自动重试。具体时间表未公开文档化，但通常在数小时内少量重试。不要依赖重试代替修复根因，因为重试次数有限且不保证持续。
下一步
投递稳定后，可加固配置以减少未来故障：
- 加上签名验证，防止未授权负载进入处理器。步骤见 签名验证指南。
- 在 HookNexus 控制台 配置监控，在投递失败时尽早发现，而不是几小时后才发现。
- 在 GitHub 学习专区 浏览更多指南，例如调试负载内容、处理特定事件类型、在 CI 中测试 webhook。
- 在 HookNexus 文档站 阅读集成文档，了解团队端点与自定义路由等高级配置。