Skip to main content

此版本的 GitHub Enterprise Server 已于以下日期停止服务 2024-09-25. 即使针对重大安全问题,也不会发布补丁。 为了获得更好的性能、更高的安全性和新功能,请升级到最新版本的 GitHub Enterprise。 如需升级帮助,请联系 GitHub Enterprise 支持

使用 Webhook 的最佳做法

在使用 Webhook 时遵循以下最佳做法以提高安全性和性能。

订阅的事件数应尽可能少

应仅订阅需要的 Webhook 事件。 这可减少服务器需要完成的工作量。 有关订阅事件的详细信息,请参阅“创建 web 挂钩”和“测试 Webhook”。

使用 Webhook 机密

Warning

为避免意外泄露敏感信息,请勿在有效负载 URL 中包含敏感信息****。 这包括你自己的 API 密钥和其他身份验证凭据。 相反,为验证 Webhook 交付是由 GitHub 发送且未被篡改,请使用 Webhook 机密。 有关详细信息,请参阅“验证 Webhook 交付”。

Webhook 密钥应选择高熵的随机文本字符串。 应以服务器可以访问的方式安全存储 Webhook 密钥。

使用 HTTPS 和 SSL 验证

应确保服务器使用 HTTPS 连接。 默认情况下,GitHub 在传递 Webhook 时将验证 SSL 证书。 GitHub 建议保持启用 SSL 验证。

在 30 秒内进行响应

服务器应在收到 Webhook 传递后 30 秒内返回 2XX 响应。 如果服务器的响应时间超过该时间,则 GitHub 将终止连接,并认为传递失败。

为确保及时响应,可能需要设置队列以异步处理 Webhook 有效负载。 服务器可以在收到 Webhook 时进行响应,然后在后台处理有效负载,而不阻止未来的 Webhook 传递。 例如,可以使用 Hookdeck 等服务或 Resque (Ruby)、RQ (Python) 或 RabbitMQ (Java) 等库。

在处理事件之前检查事件类型和操作

Webhook 事件类型有多种,并且许多事件都可以有多个操作类型。 GitHub 不断增加新的事件类型并为现有事件类型增加新的操作。 在处理 Webhook 有效负载之前,应用程序应检查该有效负载的事件类型和操作。 要确定事件类型,可以使用 X-GitHub-Event 请求头。 要确定操作类型,可以在事件负载中使用顶级 action 键。

重新传递遗漏的传递

如果服务器出现故障,应在服务器备份后重新传递遗漏的 Webhook。 有关详细信息,请参阅“重新传递 Webhook”。

使用 X-GitHub-Delivery 标头。

在重播攻击中,不良参与者截获 Webhook 交付并重新发送交付。 要防范重放攻击,可以使用 X-GitHub-Delivery 标头确保每个交付对于每个事件而言都是唯一的。

Note

如果请求重新交付,X-GitHub-Delivery 标头将与原始交付的标头相同。

其他阅读材料