Skip to main content

使用 Webhook 的最佳做法

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

订阅的事件数应尽可能少

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

使用 Webhook 机密

应为 Webhook 设置 Webhook 密钥,并验证每个 Webhook 传递的签名是否与该密钥一致。 这有助于确保 Webhook 传递是来自 GitHub 的。 有关详细信息,请参阅“验证 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 标头确保每次交付的特殊性。

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

延伸阅读