排查 webhook

缺少 webhook 交付

如果未收到预期的 webhook 交付，请确定缺失交付的发生点。

1. 触发您期望导致 webhook 交付的事件。例如，如果您的 webhook 是订阅 issues 事件的仓库 webhook，您可以在该仓库打开一个 issue。

2. 查看您 webhook 的最近交付日志。有关各类 webhook 查看方法的详细信息，请参阅 查看 webhook 交付。

   如果最近的交付日志中没有与您在上一步触发的 webhook 事件相对应的交付，则说明 GitHub 并未尝试交付。要查明原因

   1. 等待几分钟后再次检查。Webhook 交付可能需要几分钟才会出现。

   2. 确保您在配置了 webhook 的位置触发了事件。例如，如果您的 webhook 是仓库 webhook，请确保在配置该 webhook 的同一仓库中触发事件。

   3. 确保您的 webhook 已订阅您触发的事件。例如，如果您期望在打开 issue 时收到 webhook 交付，请确保 webhook 已订阅 issues 事件。

   4. 确保您的 webhook 已激活。更多信息请参阅 禁用 webhook。

   5. 确保您的 webhook 不受 OAuth 应用访问限制的影响。如果 webhook 是由 OAuth 应用代表已授权该应用的用户创建的，则当该组织对 OAuth 应用的访问受限时，组织或仓库 webhook 将自动被禁用。更多信息请参阅 关于 OAuth 应用访问限制。

   6. 检查您的事件是否触及了文档中列出的限制。例如，如果一次推送了超过三个标签，则 push 事件不会为该次推送触发。有关每个事件的文档化限制的更多信息，请参阅 Webhook 事件和负载。

   7. 检查 githubstatus.com 上的 webhook 状态。

   如果最近的交付日志显示交付时出现错误，则说明 GitHub 已尝试交付，但交付未成功。通常是由于您的服务器出现问题。您可以参考以下章节帮助解决具体错误。

3. 查看服务器日志。日志信息取决于服务器处理 webhook 交付的代码。为帮助诊断服务器上的问题，您可能需要在代码中添加额外的日志语句。

不能超过 20 条 webhook

每种事件类型最多可以创建 20 条仓库或组织 webhook。如果尝试创建更多，则会收到错误提示，指出不能超过 20 条 webhook。

如果需要超过 20 条 webhook，您可以运行一个代理来接收来自 GitHub 的 webhook 并将其转发到任意数量的目标 URL。

不支持 URL 主机 localhost

不能使用 localhost 或 127.0.0.1 作为 webhook URL。

要将 webhook 交付到本地服务器进行测试，您可以使用 webhook 转发服务。更多信息请参阅 测试 webhook 或访问 https://smee.io/。

连接主机失败

failed to connect to host 错误发生在 GitHub 试图交付 webhook，但无法将 webhook 的 URL 解析为 IP 地址，或网络限制阻止了对该主机的连接。

要检查主机名是否能解析为 IP 地址，您可以使用 nslookup。例如，如果您的负载 URL 为 https://octodex.github.com/webhooks，可以运行 nslookup octodex.github.com。如果主机名无法解析为 IP 地址，nslookup 命令会提示服务器找不到该主机名。

请确保您的服务器允许来自 GitHub IP 地址的连接。您可以使用 GET /meta 端点获取当前 GitHub IP 地址列表。更多信息请参阅 REST API 元数据端点。GitHub 会不时更改其 IP 地址，因此请定期更新您的 IP 允许列表。

连接网络失败

failed to connect to network 错误表示当 GitHub 试图交付 webhook 时，您的服务器拒绝了连接。

请确保您的服务器允许来自 GitHub IP 地址的连接。您可以使用 GET /meta 端点获取当前 GitHub IP 地址列表。更多信息请参阅 REST API 元数据端点。GitHub 会不时更改其 IP 地址，因此请定期更新您的 IP 允许列表。

超时

timed out 错误表示 GitHub 在交付 webhook 后的 10 秒内未收到服务器的响应。

您的服务器应在收到 webhook 交付后 10 秒内返回 2xx 响应。如果服务器响应时间超过此限制，GitHub 将终止连接并将交付标记为失败。

为及时响应，您可以设置队列异步处理 webhook 负载。服务器在收到 webhook 时立即返回响应，然后在后台处理负载，而不会阻塞后续 webhook 交付。例如，您可以使用 Hookdeck 等服务，或使用 Resque（Ruby）、RQ（Python）或 RabbitMQ 等库。

对等证书无法使用给定的 CA 证书进行验证

此错误表示您的服务器证书存在问题。最常见的问题包括：

• 您的服务器使用自签名证书。
• 您的服务器在建立连接时未发送完整的证书链。

要帮助诊断该问题，您可以使用 SSL Labs 的 SSL 服务器测试。该服务仅适用于 HTTPS 默认端口（443），且仅能测试可从 Internet 访问的服务器。

您也可以使用 openssl 来诊断问题。在终端中运行 openssl s_client -connect HOST:PORT，将 HOST 替换为服务器主机名，PORT 替换为端口，例如 openssl s_client -connect example.com:443。在输出中查找 verify error 以定位问题。

无效的 HTTP 响应

invalid HTTP response 错误发生在您的服务器对来自 GitHub 的 webhook 交付返回 4xx 或 5xx 状态码时。

请将服务器配置为返回 2xx 状态码。如果返回 4xx 或 5xx 状态码，GitHub 将记录交付为失败。

Webhook 交付顺序错乱

GitHub 可能会以与事件实际发生顺序不同的顺序交付 webhook。如果需要了解事件相对于另一个事件的发生时间，请使用交付负载中包含的时间戳。

Webhook 交付不是即时的

Webhook 交付可能需要几分钟才能送达并出现在最近交付日志中。在断定 webhook 交付失败之前，请等待几分钟后再检查。

如果您的账号出现 webhook 交付激增，GitHub 可能会临时限制交付速率。如果您的 webhook 交付被 GitHub 限速，每个受影响的交付的 throttled_at 属性会显示限速的时间戳。您可以通过 REST API 检查此信息，参见 列出仓库 webhook 的交付。

为避免延迟，请仅订阅账户真正需要的 webhook 事件，从而降低交付频率。参见 “使用 webhook 的最佳实践”。

签名验证失败

您应使用 webhook secret 和 X-Hub-Signature-256 头部来验证 webhook 交付确实来自 GitHub。更多信息请参阅 验证 webhook 交付。

如果您确信负载来自 GitHub，但签名验证仍失败

• 确保已为 webhook 配置 secret。如果未配置 secret，则 X-Hub-Signature-256 头部不会出现。有关为 webhook 配置 secret 的详细信息，请参阅 编辑 webhook。
• 确保使用了正确的头部。GitHub 推荐使用 X-Hub-Signature-256 头部，它采用 HMAC‑SHA256 算法。X-Hub-Signature 头部使用 HMAC‑SHA1 算法，仅在遗留情况下保留。
• 确保使用了正确的算法。如果使用 X-Hub-Signature-256 头部，则应使用 HMAC‑SHA256 算法。
• 确保使用了正确的 webhook secret。如果不知道 webhook secret 的值，您可以更新 webhook 的 secret。更多信息请参阅 编辑 webhook。
• 确保在验证之前未修改负载和头部。例如，如果使用代理或负载均衡器，请确保它们不会修改负载或头部。
• 如果您的语言和服务器实现指定了字符编码，请确保以 UTF-8 处理负载。Webhook 负载可能包含 Unicode 字符。