Webhooks 故障排除

了解如何诊断和解决 Webhooks 的常见错误。

本文内容

缺少 Webhook 传递

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

  1. 触发您希望导致 Webhook 传递的事件。例如，如果您的 Webhook 是订阅了 `issues` 事件的仓库 Webhook，则可以在该仓库中打开一个问题。

  2. 查看 Webhook 的最近传递日志。有关如何针对每种 Webhook 类型执行此操作的信息，请参阅“查看 Webhook 传递”。

    如果最近传递日志不包含与您在上一步中触发的 Webhook 事件相对应的传递，则 GitHub 未尝试进行传递。要确定原因

    1. 等待几分钟，然后再次检查。Webhook 传递可能需要几分钟才能显示。

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

    3. 确保您的 Webhook 已订阅您触发的事件。例如，如果您希望在打开问题时进行 Webhook 传递，请确保您的 Webhook 已订阅 `issues` 事件。

    4. 确保您的 Webhook 处于活动状态。有关更多信息，请参阅“禁用 Webhooks”。

    5. 确保您的 Webhook 未受 OAuth 应用访问限制的影响。如果您的 Webhook 是由 OAuth 应用代表授权该 OAuth 应用的用户创建的，则如果它是针对限制了 OAuth 应用访问权限的组织的组织或仓库 Webhook，则该 Webhook 将被自动禁用。有关更多信息，请参阅“关于 OAuth 应用访问限制”。

    6. 检查您的事件是否可能触及了已记录的限制。例如，如果您一次推送超过三个标签，则不会为该推送触发 `push` 事件。有关每个事件的已记录限制的更多信息，请参阅“Webhook 事件和有效负载”。

    7. 在 githubstatus.com 上检查 Webhooks 的状态。

    如果最近传递日志指示传递存在错误，则 GitHub 尝试了传递，但传递不成功。这通常是由于您的服务器存在问题。您可以参考以下部分以帮助解决特定的错误。

  3. 查看服务器的日志。日志中的信息取决于服务器运行以处理 Webhook 传递的代码。为了帮助您诊断服务器上的问题，您可能希望向代码中添加其他日志语句。

无法拥有超过 20 个 Webhooks

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

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

不支持 URL 主机 localhost

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

要将 Webhook 传递到您的本地服务器以进行测试，您可以使用 Webhook 转发服务。有关更多信息，请参阅“测试 Webhooks”或访问 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 响应。如果您的服务器需要更长时间才能响应，则 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`。

无效的 HTTP 响应

当您的服务器返回 4xx 或 5xx 状态以响应来自 GitHub 的 Webhook 传递时，会发生 `无效的 HTTP 响应` 错误。

您应该将服务器配置为返回 2xx 状态。如果您的服务器返回 4xx 或 5xx 状态，GitHub 将记录传递失败。

Webhook 传递顺序错误

GitHub 可能以与事件发生顺序不同的顺序传递 Webhook。如果您需要了解事件相对于另一个事件发生的时间，则应使用传递有效负载中包含的时间戳。

Webhook 传递不是立即的

Webhook 传递可能需要几分钟才能传递并出现在最近传递日志中。在得出 Webhook 传递失败的结论之前，请等待几分钟，然后再次检查。

如果您的帐户遇到 Webhook 传递量激增的情况，GitHub 可能会暂时限制发送到您帐户的传递速率。如果您的 Webhook 传递因 GitHub 而减速，则每个受影响传递的 throttled_at 属性将显示传递被限制的时间戳。您可以使用 REST API 检查此属性，请参阅“列出存储库 Webhook 的传递”。

为避免延迟，请仅订阅帐户所需的 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 字符。