Webhooks

Webhooks 通过实时通知将极狐GitLab 连接到您的其他工具和系统。 当极狐GitLab 中发生重要事件时，Webhooks 会将该信息直接发送到您的外部应用程序。 通过响应合并请求、代码推送和议题更新来构建自动化工作流。

借助 Webhooks，您的团队可以在发生变化时保持同步：

• 当极狐GitLab 议题发生变化时，外部问题跟踪器会自动更新。
• 聊天应用程序会在流水线完成时通知团队成员。
• 当代码到达主分支时，自定义脚本会部署应用程序。
• 监控系统可跟踪整个组织的开发活动。

Webhook 事件#

极狐GitLab 中的各种事件都可以触发 Webhooks。例如：

• 将代码推送到仓库。
• 在议题上发表评论。
• 创建合并请求。

Webhook 限制#

JihuLab.com 强制执行 Webhook 限制，包括：

• 每个项目或群组的最大 Webhook 数量。
• 每分钟的 Webhook 调用次数。
• Webhook 超时持续时间。

对于私有化部署的极狐GitLab，管理员可以修改这些限制。

Push 事件限制#

极狐GitLab 限制包含多个更改的 Push 事件的 Webhook 触发器：

• 默认限制：每次推送 3 个分支或标签。
• 超出时的行为：不会为整个 Push 事件触发任何 Webhook。
• 适用于：项目 Webhook 和系统钩子。
• 配置：私有化部署的极狐GitLab 管理员可以通过应用程序设置 API 修改 push_event_hooks_limit 设置。

如果您经常同时推送多个标签或分支并且需要 Webhook 通知，请联系您的极狐GitLab 管理员以提高此限制。

群组 Webhook#

群组 Webhook 是自定义 HTTP 回调，可针对群组及其子群组中所有项目的事件发送通知。

群组 Webhook 事件类型#

您可以将群组 Webhook 配置为监听：

• 在群组和子群组的项目中发生的所有事件
• 群组特定事件，包括群组成员事件、项目事件和子群组事件

同时存在于项目和群组中的 Webhooks#

如果您在一个群组以及该群组内的一个项目中配置了相同的 Webhook，那么这两个 Webhook 都会在该项目中发生事件时被触发。 这允许在极狐GitLab 组织的不同层级进行灵活的事件处理。

配置 Webhooks#

在极狐GitLab 中创建和配置 Webhooks 以集成到您项目的工作流中。 使用这些功能来设置满足您特定要求的 Webhooks。

创建一个 Webhook#

版本历史

• 名称和描述在极狐GitLab 16.9 中引入。
• 签名令牌文本框在极狐GitLab 19.0 中引入，带有名为 webhook_signing_token 的功能标志。默认启用。

对于新的 Webhooks，请使用签名令牌而不是秘密令牌。签名令牌会基于有效负载计算 HMAC-SHA256 签名，因此您的端点可以验证请求的真实性和完整性。秘密令牌只在请求头中提供一个纯文本值，其安全性较弱。不建议在新的 Webhooks 中使用秘密令牌。

创建一个 Webhook 以发送有关您的项目或群组中事件的通知。

先决条件：

• 对于项目 Webhook，您必须具有该项目的维护者或所有者角色。
• 对于群组 Webhook，您必须具有该群组的所有者角色。

要创建一个 Webhook：

1. 在顶部栏中，选择搜索或跳转到并找到您的项目或群组。
2. 在左侧边栏中，选择设置 > Webhooks。
3. 选择添加新的 Webhook。
4. 在 URL 中，输入 Webhook 端点的 URL。 对特殊字符使用百分号编码。
5. 可选。为 Webhook 输入名称和描述。
6. 可选。配置请求认证。使用签名令牌以获得更强的安全性：
   • 签名令牌（推荐）：选择生成签名令牌。 立即复制并保存令牌，因为它仅显示一次。 您的 Webhook 端点可以使用此令牌来验证 HMAC-SHA256 签名。
   • 秘密令牌（不推荐）：在秘密令牌字段中输入令牌。 此令牌在 X-Gitlab-Token HTTP 请求头中以纯文本形式发送，其安全性弱于签名令牌。对于新的 Webhooks，请改用签名令牌。
7. 在触发器部分，选择要触发 Webhook 的事件。
8. 可选。禁用 SSL 验证，清除启用 SSL 验证复选框。
9. 选择添加 Webhook。

签名令牌#

版本历史

• 在极狐GitLab 19.0 中引入，带有名为 webhook_signing_token 的功能标志。默认启用。

使用签名令牌验证 Webhook 有效负载是否来自极狐GitLab 且未被篡改。 与秘密令牌不同，签名令牌用于基于有效负载计算 HMAC-SHA256 签名。这意味着接收方可以独立验证收到的有效负载的真实性和完整性。

极狐GitLab Webhook 交付遵循 Standard Webhooks 规范。每个 Webhook 请求都包含 webhook-id 和 webhook-timestamp 请求头。 当配置了签名令牌时，极狐GitLab 还会包含带有 HMAC-SHA256 签名的 webhook-signature 请求头。每个签名的格式为 v1,{base64_signature}。该请求头可能包含多个以空格分隔的签名。极狐GitLab 目前发送一个签名，但这在未来可能会改变。签名是通过字符串 {message_id}.{timestamp}.{body} 计算得出的，其中：

• {message_id} 是 webhook-id 请求头的值。
• {timestamp} 是 webhook-timestamp 请求头的值。
• {body} 是原始的 JSON 请求体。

验证签名#

要在您的 Webhook 端点中验证签名：

1. 检索 webhook-id、webhook-timestamp 和 webhook-signature 请求头的值。
2. 以空格分隔 webhook-signature 的值以获取签名列表。
3. 构造消息字符串："{message_id}.{timestamp}.{body}"。
4. 解码签名令牌：去除 whsec_ 前缀，然后对其余部分进行 base64 解码。
5. 使用解码后的密钥计算 HMAC-SHA256 摘要。
6. 将摘要编码为 base64，并加上 v1, 前缀。
7. 检查计算出的签名是否与签名列表中的任何条目匹配。 使用恒定时间比较以防止计时攻击。

Ruby 示例：

ruby
1require 'base64'
2require 'openssl'
3
4def valid_signature?(signing_token, message_id, timestamp, body, received_signatures)
5  raw_key = Base64.strict_decode64(signing_token.delete_prefix('whsec_'))
6  message = "#{message_id}.#{timestamp}.#{body}"
7  digest = OpenSSL::HMAC.digest('sha256', raw_key, message)
8  expected = "v1,#{Base64.strict_encode64(digest)}"
9  received_signatures.split(' ').any? do |sig|
10    ActiveSupport::SecurityUtils.secure_compare(expected, sig)
11  end
12end

Python 示例：

python
1import base64
2import hashlib
3import hmac
4
5def valid_signature(signing_token, message_id, timestamp, body, received_signatures):
6    raw_key = base64.b64decode(signing_token.removeprefix('whsec_'))
7    message = f"{message_id}.{timestamp}.{body}".encode('utf-8')
8    digest = hmac.new(raw_key, message, hashlib.sha256).digest()
9    expected = "v1," + base64.b64encode(digest).decode('utf-8')
10    return any(
11        hmac.compare_digest(expected, sig)
12        for sig in received_signatures.split(' ')
13    )

向后兼容性#

签名令牌与现有的秘密令牌配合使用。您可以在同一个 Webhook 上同时配置两者：

• 如果配置了秘密令牌，仍会发送 X-Gitlab-Token 请求头。
• 如果配置了签名令牌，则会发送 webhook-signature 和 webhook-id 请求头。

要在不停机的情况下将使用秘密令牌的现有 Webhook 迁移到签名令牌，请在过渡期间在同一个 Webhook 上配置两种令牌。更新您的接收器，使其在 webhook-signature 存在时验证签名，否则回退到秘密令牌。

一旦您的接收器正确处理了签名，您就可以从 Webhook 设置中移除秘密令牌。

安全考虑#

为防止重放攻击，在处理有效负载之前，请验证 webhook-timestamp 中的时间戳是否是最近的。

API 永远不会返回签名令牌。

屏蔽 Webhook URL 的敏感部分#

屏蔽 Webhook URL 的敏感部分以增强安全性。 被屏蔽的部分在 Webhook 执行时会被替换为已配置的值，不会被记录，并在数据库静态时进行加密。

要屏蔽 Webhook URL 的敏感部分：

1. 在顶部栏中，选择搜索或跳转到并找到您的项目或群组。
2. 在左侧边栏中，选择设置 > Webhooks。
3. 在 URL 中，输入 Webhook 的完整 URL。
4. 要定义屏蔽部分，请选择添加 URL 屏蔽。
5. 在 URL 的敏感部分中，输入您要屏蔽的 URL 部分。
6. 在 UI 中的显示方式中，输入要显示的值以代替被屏蔽的部分。 变量名只能包含小写字母 (a-z)、数字 (0-9) 或下划线 (_)。
7. 选择保存更改。

被屏蔽的值在 UI 中显示为隐藏状态。 例如，如果您定义了变量 path 和 value，Webhook URL 可能如下所示：

plaintext
https://webhook.example.com/{path}?key={value}

自定义请求头#

版本历史

• 在极狐GitLab 16.11 中引入，带有名为 custom_webhook_headers 的功能标志。默认启用。
• 在极狐GitLab 17.0 中 GA。功能标志 custom_webhook_headers 已移除。

向 Webhook 请求添加自定义请求头，以便向外部服务进行认证。 您可以为每个 Webhook 配置最多 20 个自定义请求头。

自定义请求头必须：

• 不覆盖交付头的值。
• 仅包含字母数字字符、句点、破折号或下划线。
• 以字母开头并以字母或数字结尾。
• 不具有连续的句点、破折号或下划线。

自定义请求头在最近事件中显示为屏蔽值。

自定义 Webhook 模板#

版本历史

• 在极狐GitLab 16.10 中引入，带有名为 custom_webhook_template 的功能标志。默认启用。
• 在极狐GitLab 17.0 中 GA。功能标志 custom_webhook_template 已移除。
• 在极狐GitLab 18.4 中引入插值字段值的 JSON 序列化功能，带有名为 custom_webhook_template_serialization 的功能标志。默认禁用。
• 插值字段值的 JSON 序列化在极狐GitLab 18.6 中 GA。功能标志 custom_webhook_template_serialization 默认启用。
• 功能标志 custom_webhook_template_serialization 在极狐GitLab 18.10 中移除。

为您的 Webhook 创建自定义有效负载模板，以控制请求体中发送的数据。

创建自定义 Webhook 模板#

• 对于项目 Webhook，您必须具有该项目的维护者或所有者角色。
• 对于群组 Webhook，您必须具有该群组的所有者角色。

要创建自定义 Webhook 模板：

1. 转到您的 Webhook 配置。
2. 设置一个自定义 Webhook 模板。
3. 确保模板呈现为有效的 JSON。

在您的模板中使用事件有效负载中的字段。例如：

• 对于作业事件，使用 {{build_name}}
• 对于部署事件，使用 {{deployable_url}}

要访问嵌套属性，请使用句点分隔路径段。

自定义 Webhook 模板示例#

对于此自定义有效负载模板：

json
{
   "event": "{{object_kind}}",
   "project_name": "{{project.name}}"
}

对于 push 事件，生成的请求有效负载为：

json
{
   "event": "push",
   "project_name": "Example"
}

自定义 Webhook 模板无法访问数组中的属性。 此功能在议题 463332 中提出支持。

按分支过滤 Push 事件#

按分支名称过滤发送到 Webhook 端点的 push 事件。 使用以下过滤选项之一：

• 所有分支：接收来自所有分支的 Push 事件。
• 通配符模式：接收来自匹配通配符模式的分支的 Push 事件。
• 正则表达式：接收来自匹配正则表达式 (regex) 的分支的 Push 事件。

使用通配符模式#

要使用通配符模式进行过滤：

1. 在 Webhook 配置中，选择通配符模式。
2. 输入一个模式。 例如：
   • *-stable 匹配以 -stable 结尾的分支。
   • production/* 匹配 production/ 命名空间中的分支。

使用正则表达式#

要使用正则表达式进行过滤：

1. 在 Webhook 配置中，选择正则表达式。
2. 输入遵循 RE2 语法的正则表达式模式。

例如，要排除 main 分支，使用：

plaintext
\b(?:m(?!ain\b)|ma(?!in\b)|mai(?!n\b)|[a-l]|[n-z])\w*|\b\w{1,3}\b|\W+

配置 Webhooks 以支持双向 TLS#

版本历史

• 在极狐GitLab 16.9 中引入。

通过设置 PEM 格式的全局客户端证书，将 Webhooks 配置为支持双向 TLS。

先决条件：

• 您必须是极狐GitLab 管理员。

要为 Webhooks 配置双向 TLS：

1. 准备一个 PEM 格式的客户端证书。
2. 可选。使用 PEM 密码保护证书。
3. 配置极狐GitLab 以使用该证书。

配置完成后，极狐GitLab 会在 Webhook 连接的 TLS 握手期间将此证书呈现给服务器。

为 Webhook 流量配置防火墙#

根据极狐GitLab 发送 Webhooks 的方式，为 Webhook 流量配置防火墙：

• 从 Sidekiq 节点异步发送（最常见）
• 从 Rails 节点同步发送（在特定情况下）

当您在 UI 中测试或重试 Webhook 时，Webhooks 会从 Rails 节点同步发送。

在配置防火墙时，请确保 Sidekiq 和 Rails 节点都可以发送 Webhook 流量。

管理 Webhooks#

监控和维护您在极狐GitLab 中已配置的 Webhooks。

查看 Webhook 请求历史记录#

查看 Webhook 请求的历史记录，以监控其性能并排查问题。

先决条件：

• 对于项目 Webhook，您必须具有该项目的维护者或所有者角色。
• 对于群组 Webhook，您必须具有该群组的所有者角色。

要查看 Webhook 的请求历史记录：

1. 在顶部栏中，选择搜索或跳转到并找到您的项目或群组。
2. 在左侧边栏中，选择设置 > Webhooks。
3. 为该 Webhook 选择编辑。
4. 转到最近事件部分。

最近事件部分显示最近两天内向 Webhook 发出的所有请求。 该表格包括：

• HTTP 状态码：
  • 200-299 代码为绿色
  • 其他代码为红色
  • 投递失败为 internal error
• 触发事件
• 请求的耗时
• 请求发出的相对时间

检查请求和响应详情#

先决条件：

• 对于项目 Webhook，您必须具有该项目的维护者或所有者角色。
• 对于群组 Webhook，您必须具有该群组的所有者角色。

最近事件中的每个 Webhook 请求都有一个请求详情页面。 此页面包含以下内容的请求体和请求头：

• 极狐GitLab 从 Webhook 接收器端点收到的响应
• 极狐GitLab 发送的 Webhook 请求

要检查 Webhook 事件的请求和响应详情：

1. 在顶部栏中，选择搜索或跳转到并找到您的项目或群组。
2. 在左侧边栏中，选择设置 > Webhooks。
3. 为该 Webhook 选择编辑。
4. 转到最近事件部分。
5. 为该事件选择查看详情。

要使用相同的数据和相同的 Idempotency-Key 请求头再次发送请求，请选择重新发送请求。 如果 Webhook URL 已更改，则无法重新发送请求。 您也可以通过项目 Webhooks API 以编程方式重新发送请求。

测试 Webhook#

测试 Webhook 以确保其正常工作或重新启用已禁用的 Webhook。

先决条件：

• 对于项目 Webhook，您必须具有该项目的维护者或所有者角色。
• 对于群组 Webhook，您必须具有该群组的所有者角色。
• 要测试 push events，您的项目必须至少有一次提交。

要测试 Webhook：

1. 在顶部栏中，选择搜索或跳转到并找到您的项目或群组。
2. 在左侧边栏中，选择设置 > Webhooks 以查看此项目的所有 Webhooks。
3. 要从已配置的 Webhooks 列表中直接测试 Webhook：
   1. 找到您要测试的 Webhook。
   2. 从测试下拉列表中，选择要测试的事件类型。
4. 要在编辑时测试 Webhook：
   1. 找到您要测试的 Webhook，然后选择编辑。
   2. 对 Webhook 进行更改。
   3. 选择测试下拉列表，然后选择要测试的事件类型。

项目和群组 Webhooks 的某些事件类型不支持测试。 更多信息，请参见议题 379201。

Webhook 参考#

使用此技术参考来：

• 了解极狐GitLab Webhooks 的工作原理。
• 将 Webhooks 与您的系统集成。
• 设置、排查和优化您的 Webhook 配置。

Webhook 接收器要求#

实现快速且稳定的 Webhook 接收器端点，以确保可靠的 Webhook 交付。

缓慢、不稳定或配置错误的接收器可能会被自动禁用。 无效的 HTTP 响应被视为失败的请求。

要优化您的 Webhook 接收器：

1. 快速响应 200 或 201 状态：
   • 避免在同一个请求中处理 Webhooks。
   • 使用队列在收到 Webhooks 后处理它们。
   • 在超时限制之前响应，以防止在 JihuLab.com 上被自动禁用。
2. 处理潜在的重复事件：
   • 如果 Webhook 超时，请为重复事件做好准备。
   • 确保您的端点始终快速且稳定。
3. 最小化响应头和响应体：
   • 极狐GitLab 存储响应头和响应体以供稍后检查。
   • 限制返回头的数量和大小。
   • 考虑响应一个空响应体。
4. 使用适当的状态码：
   • 仅在 Webhook 配置错误时返回客户端错误状态响应（4xx 范围）。
   • 对于不支持的事件，返回 400 或忽略有效负载。
   • 避免对已处理的事件使用 500 服务器错误响应。

自动禁用的 Webhooks#

版本历史

• 在极狐GitLab 15.10 中为群组 Webhooks 引入。
• 在极狐GitLab 15.10 中为私有化部署的项目 Webhooks 禁用，带有名为 auto_disabling_web_hooks 的功能标志。
• 连接失败在极狐GitLab 17.11 中重命名为已禁用和暂时禁用。
• 在极狐GitLab 17.11 中更改为连续失败 40 次后永久禁用。

极狐GitLab 会自动禁用连续失败四次的项目或群组 Webhooks。

要查看自动禁用的 Webhooks：

1. 在顶部栏中，选择搜索或跳转到并找到您的项目或群组。
2. 在左侧边栏中，选择设置 > Webhooks。

在 Webhook 列表中，自动禁用的 Webhooks 显示为：

• 暂时禁用（如果它们连续失败四次）
• 已禁用（如果它们连续失败 40 次）

暂时禁用的 Webhooks#

如果 Webhooks 连续失败四次，则会被暂时禁用。 如果 Webhooks 连续失败 40 次，它们将变为永久禁用。

在以下情况下会发生失败：

• Webhook 接收器返回 4xx 或 5xx 范围内的响应代码。
• Webhook 在尝试连接到 Webhook 接收器时遇到超时。
• Webhook 遇到其他 HTTP 错误。

暂时禁用的 Webhooks 最初会被禁一分钟，随后的失败会将禁用时间延长至最多 24 小时。 在此时间段过后，这些 Webhooks 会自动重新启用。

永久禁用的 Webhooks#

如果 Webhooks 连续失败 40 次，则会被永久禁用。 与暂时禁用的 Webhooks 不同，这些 Webhooks 不会自动重新启用。

在极狐GitLab 17.10 及更早版本中永久禁用的 Webhooks 经过了数据迁移。 尽管 UI 可能显示它们有 40 次失败，但这些 Webhooks 在最近事件中可能只显示四次失败。

重新启用已禁用的 Webhooks#

要重新启用已禁用的 Webhook，请发送一个测试请求。 如果测试请求返回 2xx 范围内的响应代码，则该 Webhook 会被重新启用。

交付头#

版本历史

• X-Gitlab-Webhook-UUID 头在极狐GitLab 16.2 中引入。
• Idempotency-Key 头在极狐GitLab 17.4 中引入。
• webhook-id 和 webhook-timestamp 头在极狐GitLab 19.0 中引入。
• webhook-signature 头在极狐GitLab 19.0 中引入，带有名为 webhook_signing_token 的功能标志。默认启用。

极狐GitLab 在发送到您端点的 Webhook 请求中包含以下请求头。

Webhook 主体中的图片 URL 显示#

极狐GitLab 会将 webhook 主体中的相对图片引用重写为绝对 URL。

图片 URL 重写示例#

如果合并请求、评论或 Wiki 页面中的原始图片引用为：

markdown
![一个带有相对 URL 的 Markdown 图片。](/uploads/$sha/image.png)

则 webhook 主体中重写后的图片引用将为：

markdown
![一个带有绝对 URL 的 Markdown 图片。](https://gitlab.example.com/-/project/:id/uploads/<SHA>/image.png)

此示例假设：

• 极狐GitLab 安装在 gitlab.example.com。
• 项目 ID 为 123。

图片 URL 重写的例外情况#

极狐GitLab 在以下情况下不会重写图片 URL：

• 它们已经使用 HTTP、HTTPS 或协议相对 URL。
• 它们使用了 Markdown 高级特性，例如链接标签。