跳至主要内容

使用 Webhook 的最佳实践

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

订阅最少数量的事件

你应该只订阅你需要的 Webhook 事件。这将减少服务器需要完成的工作量。有关订阅事件的更多信息,请参阅“创建 Webhook”和“编辑 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 响应进行响应。如果您的服务器响应时间超过 10 秒,则 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 标头将与原始传送中的标头相同。

延伸阅读