Skip to main content

使用 Webhook 的最佳做法

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

订阅的事件数应尽可能少

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

使用 Webhook 机密

Warning

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

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

使用 HTTPS 和 SSL 验证

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

允许 GitHub 的 IP 地址

可以为服务器设置 IP 允许列表,并添加 GitHub 用于 Webhook 传递的 IP 地址。 这可以阻止对服务器的欺骗请求。

可以使用 GET /meta 端点来查找 GitHub 的当前 IP 地址列表。 有关详细信息,请参阅“元数据的 REST API 终结点”。 GitHub 有时会对其 IP 地址进行更改,因此应定期更新 IP 允许列表。

有关详细信息,请参阅“关于 GitHub 的 IP 地址”。

在 10 秒内进行响应

服务器应在收到 Webhook 传递后 10 秒内返回 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 标头将与原始交付的标头相同。

其他阅读材料