GitHub 文档 - Webhook 故障排除

缺少 Webhook 交付

如果您没有收到预期的 Webhook 交付，则应确定交付丢失的位置。

触发您期望会产生 Webhook 交付的事件。例如，如果您的 Webhook 是订阅了 issues 事件的仓库 Webhook，则可以在该仓库中打开一个问题。
查看 Webhook 的最近交付日志。有关如何针对每种 Webhook 类型执行此操作的信息，请参阅“查看 Webhook 交付”。

如果最近交付日志中不包含与您在上一步骤中触发的 Webhook 事件相对应的交付，则表示 GitHub 未尝试交付。要确定原因
1. 等待几分钟，然后再次检查。Webhook 交付可能需要几分钟才能显示。
2. 确保您在配置 Webhook 的位置触发了事件。例如，如果您的 Webhook 是仓库 Webhook，请确保您在配置 Webhook 的同一仓库中触发了事件。
3. 确保您的 Webhook 订阅了您触发的事件。例如，如果您期望在打开问题时收到 Webhook 交付，请确保您的 Webhook 订阅了 issues 事件。
4. 确保您的 Webhook 处于活动状态。有关更多信息，请参阅“禁用 Webhook”。
5. 确保您的 Webhook 未受 OAuth 应用访问限制的影响。如果您的 Webhook 是由 OAuth 应用代表授权该应用的用户创建的，则如果该 Webhook 是针对限制了 OAuth 应用访问权限的组织的组织或仓库 Webhook，则该 Webhook 将自动禁用。有关更多信息，请参阅“关于 OAuth 应用访问限制”。
6. 检查您的事件是否可能触及了已记录的限制。例如，如果您一次推送超过三个标签，则不会触发该推送的 push 事件。有关每个事件的已记录限制的更多信息，请参阅“Webhook 事件和有效负载”。
7. 检查 Webhook 状态，请访问 githubstatus.com。
如果最近的交付日志显示交付过程中出现错误，则表示 GitHub 尝试了交付，但交付失败。这通常是由于您的服务器出现问题导致的。您可以参考以下部分来帮助解决特定错误。
查看您服务器的日志。日志中的信息取决于您的服务器运行的处理 Webhook 交付的代码。为了帮助您诊断服务器上的问题，您可能需要在代码中添加额外的日志语句。

Webhook 数量不能超过 20 个

您可以为每个事件类型创建最多 20 个仓库或组织 Webhook。如果您尝试创建更多，您将收到一条错误消息，指出您不能拥有超过 20 个 Webhook。

如果您需要超过 20 个 Webhook，您可以运行一个代理，该代理接收来自 GitHub 的 Webhook 并将它们转发到无限数量的目标 URL。

URL 主机 localhost 不受支持

您不能使用 localhost 或 127.0.0.1 作为 Webhook URL。

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

无法连接到主机

无法连接到主机 错误发生在 GitHub 尝试交付 Webhook 但无法将 Webhook 的 URL 解析为 IP 地址时。

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

无法连接到网络

无法连接到网络 错误表示当 GitHub 尝试交付 Webhook 时，您的服务器拒绝了连接。

您需要确保您的服务器允许来自 GitHub IP 地址的连接。您可以使用 `GET /meta` 端点查找 GitHub 当前的 IP 地址列表。有关更多信息，请参阅“元数据的 REST API 端点”。GitHub 偶尔会更改其 IP 地址，因此您应该定期更新您的 IP 允许列表。

超时

`超时` 错误表示 GitHub 在发送 webhook 后 10 秒内没有收到来自您服务器的响应。

您的服务器应该在收到 webhook 传递后 10 秒内以 2xx 响应进行响应。如果您的服务器响应时间超过 10 秒，GitHub 将终止连接并将传递视为失败。

为了及时响应，您可能需要设置一个队列来异步处理 webhook 负载。您的服务器可以在收到 webhook 时进行响应，然后在后台处理负载，而不会阻塞未来的 webhook 传递。例如，您可以使用像 Hookdeck 这样的服务或像 Resque (Ruby)、RQ (Python) 或 RabbitMQ 这样的库。

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

此错误表示与您的服务器证书相关的问题。最常见的问题是

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

要帮助诊断问题，您可以使用 SSL Labs 的 SSL 服务器测试。此服务只能与 HTTPS 的默认端口（端口 443）一起使用，并且只能与可从互联网访问的服务器一起使用。

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

为了避免延迟，请仅订阅您的帐户所需的 webhook 事件，从而减少传递频率。请参阅“使用 webhook 的最佳实践”。

签名验证失败

您应该使用 webhook 密钥和 X-Hub-Signature-256 标头来验证 webhook 传递是否来自 GitHub。有关更多信息，请参阅“验证 webhook 传递”。

如果您确定有效负载来自 GitHub，但签名验证失败

确保您已为您的 webhook 配置了密钥。如果您没有为您的 webhook 配置密钥，则 X-Hub-Signature-256 标头将不会存在。有关为您的 webhook 配置密钥的更多信息，请参阅“编辑 webhook”。
确保您使用的是正确的标头。GitHub 建议您使用 X-Hub-Signature-256 标头，该标头使用 HMAC-SHA256 算法。X-Hub-Signature 标头使用 HMAC-SHA1 算法，仅出于遗留目的而包含。
确保您使用的是正确的算法。如果您使用的是 X-Hub-Signature-256 标头，则应使用 HMAC-SHA256 算法。
确保您使用的是正确的 webhook 密钥。如果您不知道 webhook 密钥的值，您可以更新 webhook 的密钥。有关更多信息，请参阅“编辑 webhook”。
确保在验证之前未修改有效负载和标头。例如，如果您使用代理或负载均衡器，请确保代理或负载均衡器不会修改有效负载或标头。
如果您的语言和服务器实现指定了字符编码，请确保您将有效负载处理为 UTF-8。Webhook 有效负载可能包含 Unicode 字符。

排查 Webhook 问题

本文内容