跳到主要内容

使用 Webhook 的最佳实践

遵循以下最佳实践,可以提高使用 Webhook 的安全性和性能。

订阅最少数量的事件

您应该只订阅您需要的 Webhook 事件。这将减少服务器需要执行的工作量。有关订阅事件的更多信息,请参阅“创建 Webhooks”和“编辑 Webhooks”。

使用 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 响应进行响应。如果您的服务器响应时间超过 10 秒,则 GitHub 将终止连接并将交付视为失败。

为了及时响应,您可能需要设置一个队列来异步处理 Webhook 有效负载。您的服务器可以在收到 Webhook 时进行响应,然后在后台处理有效负载,而不会阻塞未来的 Webhook 交付。例如,您可以使用诸如Hookdeck之类的服务或诸如Resque(Ruby)、RQ(Python)或RabbitMQ(Java)之类的库。

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

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

重新交付错过的交付

如果您的服务器宕机,则服务器恢复运行后,您应重新交付错过的 Webhook。有关更多信息,请参阅“重新交付 Webhooks”。

使用X-GitHub-Delivery头部

在重放攻击中,恶意行为者会拦截 Webhook 交付并重新发送交付。为了防止重放攻击,您可以使用X-GitHub-Delivery头部来确保每个交付对每个事件都是唯一的。

注意

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

进一步阅读