• Webhook 事件
• Webhook limits
• 群组 Webhook
• 配置 webhooks
  • 创建 webhook
  • 隐藏 webhook URL 中的敏感部分
  • 自定义标头
  • 自定义 webhook 模板
    • 创建自定义 webhook 模板
    • 自定义模板示例
  • 通过分支过滤推送事件
    • 使用通配模式
    • 使用正则表达式
  • 配置 webhook 以支持 mutual TLS (SELF-MANAGED ONLY)
  • 为 webhook 流量配置防火墙
• 管理 webhooks
  • 查看 webhook 请求历史
    • 检查请求和响应详情
  • 测试 webhook
• Webhook 参考
  • Webhook 接受器要求
  • 自动禁用 webhook
    • 暂时禁用 webhooks
    • 永久禁用 webhook
    • 重新启用禁用的 webhook。
  • 传递的标头
  • webhook body 中图片 URL 的显示
    • 图片 URL 重写示例
    • 图片 URL 重写例外
• 相关主题

Webhook

Webhook 是自定义的 HTTP 回调，此回调将极狐GitLab 中发生的事件的 JSON 数据发送到配置的 URI。

您可以使用 webhook 来：

• 触发 CI/CD 作业。
• 更新外部问题跟踪器。
• 部署到生产服务器。

Webhook 事件

极狐GitLab 中不同的事件都可以触发 webhook。比如：

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

有关事件的完整列表和 webhook 负载中发送的 JSON 数据，请参阅webhook 事件。

Webhook limits

JihuLab.com 强制 webhook 限制，包括：

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

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

群组 Webhook

您可以配置一个群组 Webhook，它由群组中所有项目发生的事件触发。如果您在群组和项目中配置相同的 Webhook，它们都由项目中的事件触发。

群组 Webhook 也可以配置为侦听特定于群组的事件，包括：

• 群组成员事件
• 子组事件
• 子群组事件。

配置 webhooks

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

创建 webhook

• 名称 和 描述 引入于极狐GitLab 16.9。

创建 webhook 来发送项目或群组中的事件的通知。

先决条件：

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

要创建 Webhook：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或群组。
2. 选择 设置 > Webhook。
3. 选择 添加新 Webhook。
4. 在 URL 中，输入 Webhook 端点的 URL。如果 URL 包含一个或多个特殊字符，则该 URL 必须是百分比编码的。
5. 可选。在 名称 和 描述 中，输入 Webhook 的名称和描述。
6. 可选。在 Secret token 中，输入一个令牌来验证请求。
7. 在 触发器 部分，选择事件来触发 Webhook。
8. 可选。要禁用 SSL 验证，请清除 启用 SSL 验证 复选框。
9. 选择 添加 Webhook。

密钥令牌与 X-Gitlab-Token HTTP 标头一起发送，Webhook 端点可以使用此令牌验证请求的合法性。

隐藏 webhook URL 中的敏感部分

• 引入于极狐GitLab 15.5，使用名为 webhook_form_mask_url 的功能标志。默认禁用。
• 在极狐GitLab 15.7 中 GA。功能标志 webhook_form_mask_url 被移除。

隐藏 webhook URL 中的敏感部分以加强安全。当 webhook 被执行时，隐藏部分被配置的值所替换，且不会被记录，另外在数据库中以加密形式存储。

要隐藏 webhook URL 中的敏感部分：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或群组。
2. 选择 设置 > Webhook。
3. 在 URL 中，输入 webhook 的完整 URL。
4. 要定义隐藏的部分，请选择 隐藏 URL 中的部分。
5. 在 URL 中的敏感部分 中，输入您要隐藏的部分。
6. 在 UI 中的样子 中，输入要显示而不是隐藏部分的值。变量名称必须只包含小写字母 (a-z)、数字 (0-9) 或下划线 (_)。
7. 选择 保存更改。

隐藏值在 UI 中显示为隐藏。例如，如果已定义变量 path 和 value，webhook URL 可能如下所示：

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 被移除。

为您的 webhook 创建一个自定义负载模板，以控制请求正文中发送的数据。

创建自定义 webhook 模板

• 对于项目 webhook，您必须至少具有项目的维护者角色。
• 对于群组 webhook，您必须具有群组的所有者角色。

要创建自定义 webhook 模板：

1. 转到您的 webhook 配置。
2. 设置自定义 webhook 模板。
3. 确保模板渲染为有效的 JSON。

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

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

为了访问嵌套的属性，请使用点分隔路径段。

自定义模板示例

对于此自定义负载模板：

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

The resulting request payload for a push event is:

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

自定义 webhook 模板无法访问数组属性。

通过分支过滤推送事件

过滤器 push 事件通过分支名称发送到您的 webhook 端点。可使用如下过滤器选项：

• 所有分支：从所有分支接收推送事件。
• 通配符模式：从与通配符模式匹配的分支接收推送事件。
• 正则表达式：从与正则表达式匹配的分支接收推送事件。

使用通配模式

通过使用通配模式来过滤：

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

使用正则表达式

通过正则表达式来过滤：

1. 在 webhook 配置中，选择 正则表达式。
2. 输入一个正则表达式，遵循 RE2 语法。

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

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

配置 webhook 以支持 mutual TLS (SELF-MANAGED ONLY)

• 引入于极狐GitLab 16.9。

通过设置全局客户端证书（PEM 格式）来配置 webhook 以支持 mutual TLS。

先决条件：

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

要为 webhook 配置 mutual TLS：

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

::Tabs

:::TabTitle Linux package (Omnibus)

1. Edit /etc/gitlab/gitlab.rb:

   gitlab_rails['http_client']['tls_client_cert_file'] = '<PATH TO CLIENT PEM FILE>'
   gitlab_rails['http_client']['tls_client_cert_password'] = '<OPTIONAL PASSWORD>'
   

2. 保存文件并重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

:::TabTitle Docker

1. 编辑 docker-compose.yml：

   version: "3.6"
   services:
     gitlab:
       image: 'gitlab/gitlab-ee:latest'
       restart: always
       hostname: 'gitlab.example.com'
       environment:
         GITLAB_OMNIBUS_CONFIG: |
            gitlab_rails['http_client']['tls_client_cert_file'] = '<PATH TO CLIENT PEM FILE>'
            gitlab_rails['http_client']['tls_client_cert_password'] = '<OPTIONAL PASSWORD>'
   

2. 保存文件并重启极狐GitLab：

   docker compose up -d
   

:::TabTitle Self-compiled (source)

1. 编辑 /home/git/gitlab/config/gitlab.yml：

   production: &base
     http_client:
       tls_client_cert_file: '<PATH TO CLIENT PEM FILE>'
       tls_client_cert_password: '<OPTIONAL PASSWORD>'
   

2. 保存文件并重启极狐GitLab：

   # For systems running systemd
   sudo systemctl restart gitlab.target
   
   # For systems running SysV init
   sudo service gitlab restart
   

::EndTabs

配置后，极狐GitLab 在 webhook 连接的 TLS 握手期间向服务器呈现此证书。

为 webhook 流量配置防火墙

基于极狐GitLab 发送的 webhooks 来为 webhook 流量配置防火墙：

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

当极狐GitLab 从 Rails 节点同步发送 webhooks 时：

• 在 UI 中测试 webhook
• 在 UI 中重试 webhook

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

管理 webhooks

在极狐GitLab 中监控并维护您配置的 webhooks。

查看 webhook 请求历史

• 针对群组 webhook 的 近期事件 引入于极狐GitLab 15.3。

查看 webhook 请求历史来监控它们的性能和故障排查问题。

先决条件：

• 对于项目 webhook，您必须至少具有项目的维护者角色。
• 对于群组 webhook，您必须具有群组的所有者角色。

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

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

近期事件 部分显示了过去两天内对 webhook 所做的所有请求。该表包括：

• HTTP 状态代码：
  • 绿色的 200-299 代码
  • 其他代码的红色
  • internal error 用于失败的交付
• 触发事件
• 请求的经过时间
• 请求的相对时间

检查请求和响应详情

先决条件：

• 对于项目 webhook，您必须至少具有项目的维护者角色。
• 对于组 webhook，您必须具有组的所有者角色。

每个 webhook 请求在 Recent events 中都有一个 Request details 页面。此页包含标头的内容和正文：

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

要检查 webhook 事件的请求和响应详细信息：

1. 在左侧边栏中，选择 搜索或前往 并找到您的项目或组。
2. 选择 设置 > Webhooks。
3. 选择 webhook 的 编辑。
4. 转到 最近事件 部分。
5. 选择事件的 查看详细信息。

要使用相同的数据和相同的 Idempotency-Key 标头) 再次发送请求，选择 Resend Request。如果 webhook URL 已经发生变化，您无法重新发送请求。要以编程方式重新发送，可以参考我们的 API 文档。

测试 webhook

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

先决条件：

• 对于项目 webhook，您必须至少具有项目的维护者角色。
• 对于组 webhook，您必须具有组的所有者角色。
• 为了测试 push events，您的项目必须至少有一个提交。

要测试 webhook：

1. 在左侧边栏中，选择 搜索或前往 并找到您的项目或组。
2. 选择 设置 > Webhooks。
3. 在配置的 webhook 列表中，找到您要测试的 webhook。
4. 从 测试 下拉列表中，选择要测试的事件类型。

或者，您也可以从其编辑页面测试 webhook。

测试不支持某些类型的事件的项目和组 webhook。

Webhook 参考

使用此参考来：

• 了解极狐GitLab webhook 的工作原理。
• 将 webhook 集成到您的系统中。
• 设置、故障排除和优化您的 webhook 配置。

Webhook 接受器要求

实现快速且稳定的 webhook 接收器请求端点来确保可靠地传递 webhook。

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

要优化您的 webhook 接收器：

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

自动禁用 webhook

• 项目 webhook 在极狐GitLab 15.7 中可用。功能标志 web_hooks_disable_failed 被移除。
• 群组 webhook 引入于极狐GitLab 15.10
• 在极狐Gitlab 15.10 中针对私有狐部署禁用，使用名为 auto_disabling_web_hooks 的功能标志。

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

要查看自动禁用的 webhook：

1. 在左侧导航栏，选择 搜索或前往 并找到您的项目或群组。
2. 选择 设置 > webhooks。

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

• 失败连接 用于暂时禁用的 webhook
• 连接失败 用于永久禁用的 webhook

暂时禁用 webhooks

如果发生如下情况，webhook 将被暂时禁用：

• 返回 5xx 范围内的响应代码。
• 遇到超时。
• 遇到其他 HTTP 错误。

这些 webhook 最初被禁用一分钟后，禁用时间在后续失败中延长，最多为 24 小时。

永久禁用 webhook

如果返回 4xx 范围内的响应码，webhook 将被永久禁用，因为这意味着错误配置。

重新启用禁用的 webhook。

• 引入于极狐GitLab 15.2，使用名为 webhooks_failed_callout 的功能标志。默认禁用。
• 在极狐GitLab 15.7 中 GA。功能标志 webhooks_failed_callout 被移除。

要重新启用临时或永久禁用的 webhook：

• 发送测试请求到 webhook。

如果测试请求返回 2xx 范围内的响应代码，则 webhook 将被重新启用。

传递的标头

• X-Gitlab-Event-UUID 标头引入于极狐GitLab 14.8。
• X-Gitlab-Instance 标头引入于极狐GitLab 15.5。
• X-Gitlab-Webhook-UUID 标头引入于极狐GitLab 16.2。
• Idempotency-Key 标头引入于极狐GitLab 17.4。

极狐GitLab 在 webhook 请求中包含如下标头：

webhook body 中图片 URL 的显示

极狐GitLab 重写 webhook body 中的相对图片引用为绝对 URL。

图片 URL 重写示例

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

![image](/uploads/$sha/image.png)

在 webhook body 中的图片引用将被重写为：

![image](https://gitlab.example.com/example-group/example-project/uploads/<SHA>/image.png)

此示例假定：

• 极狐GitLab 安装在 gitlab.example.com 上。
• 项目位于 example-group/example-project 中。

图片 URL 重写例外

当发生以下情况时，极狐GitLab 不会重写图片 URL：

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

相关主题

• Webhook 事件和 webhook JSON 载荷
• 项目 webhooks API
• 群组 webhooks API
• 系统勾子 API
• 故障排查