Webhooks

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

使用 webhooks，您的团队在发生更改时保持同步：

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

Webhook 事件#

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

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

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

Webhook 限制#

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

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

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

群组 Webhooks#

群组 webhooks 是自定义 HTTP 回调，用于发送有关群组及其子群组中的所有项目事件的通知。

群组 Webhook 事件类型#

您可以配置群组 webhooks 以监听：

• 群组和子群组中的项目中发生的所有事件。
• 群组特定事件：
  • 群组成员事件。
  • 项目事件
  • 子群组事件。

项目和群组中的 Webhooks#

如果您在群组和该群组中的项目中配置相同的 webhooks，则这两个 webhooks 会在该项目中触发事件。这允许在极狐GitLab 组织的不同级别进行灵活的事件处理。

配置 Webhooks#

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

创建 Webhook#

版本历史

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

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

先决条件：

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

要创建 webhook：

1. 在左侧边栏中，选择 搜索或转到 并找到您的项目或群组。
2. 选择 设置 > Webhooks。
3. 选择 添加新 webhook。
4. 在 URL 中，输入 webhook 端点的 URL。对特殊字符使用百分号编码。
5. 可选。为 webhook 输入 名称 和 描述。
6. 可选。在 密钥令牌 中，输入一个令牌以验证请求。
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 的敏感部分以增强安全性。执行 webhooks 时，掩盖的部分将替换为配置的值，不会被记录，并在数据库中静态加密。

要掩盖 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}

自定义 Headers#

版本历史

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

为 webhook 请求添加自定义 headers 以进行外部服务的身份验证。您可以为每个 webhook 配置最多 20 个自定义 headers。

自定义 headers 必须：

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

自定义 headers 在 最近事件 中显示为掩盖值。

自定义 Webhook 模板#

版本历史

• 在极狐GitLab 16.10 中引入，使用名为 custom_webhook_template 的功能标志 。默认启用。
• 在极狐GitLab 17.0 中 GA。功能标志 custom_webhook_template 移除。

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

创建自定义 Webhook 模板#

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

要创建自定义 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 端点的 push 事件。使用以下过滤选项之一：

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

使用通配符模式#

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

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

使用正则表达式#

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

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

例如，要排除 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 节点同步发送（在特定情况下）

在以下情况下，webhooks 从 Rails 节点同步发送：

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

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

管理 Webhooks#

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

查看 Webhook 请求历史#

版本历史

• 群组 webhooks 的 最近事件 在极狐GitLab 15.3 中引入。

查看 webhook 请求的历史记录以监控其性能和排除故障。

先决条件：

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

要查看 webhook 的请求历史：

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

最近事件 部分显示在过去两天内对 webhook 的所有请求。表格包括：

• HTTP 状态码：
  • 绿色表示 200-299 代码
  • 红色表示其他代码
  • 内部错误 表示传递失败
• 触发的事件
• 请求的经过时间
• 请求发出的相对时间

检查请求和响应详细信息#

先决条件：

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

在 最近事件 中，每个 webhook 请求都有一个 请求详细信息 页面。该页面包含以下内容的正文和 headers：

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

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

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

要使用相同的数据和相同的 Idempotency-Key 头 再次发送请求，请选择 重发请求。如果 webhook URL 已更改，则无法重发请求。有关编程重发的详细信息，请参阅我们的 API 文档。

测试 Webhook#

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

先决条件：

• 对于项目 webhooks，您必须至少具有项目的维护者角色。
• 对于群组 webhooks，您必须具有群组的所有者角色。
• 要测试 push 事件，您的项目必须至少有一个提交。

要测试 webhook：

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

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

对于项目和群组 webhooks，某些类型的事件不支持测试。

Webhook 参考#

使用此技术参考来：

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

Webhook 接收器要求#

实现快速且稳定的 webhook 接收器端点，以确保可靠的 webhook 传递。

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

要优化您的 webhook 接收器：

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

自动禁用 Webhooks#

版本历史

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

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

要查看自动禁用的 webhooks：

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

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

• 暂时禁用 用于 暂时禁用的 webhooks
• 已禁用 用于 永久禁用的 webhooks

暂时禁用的 Webhooks#

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

失败发生在以下情况下：

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

暂时禁用的 webhooks 最初禁用一分钟，随着后续失败的次数而增加，最长可达 24 小时。经过此段时间后，这些 webhooks 将自动重新启用。

永久禁用的 Webhooks#

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

在极狐GitLab 17.10 及更早版本中永久禁用的 webhooks 经历了数据迁移。这些 webhooks 可能在 最近事件 中显示四个失败，即使 UI 可能表明它们有 40 次失败。

重新启用禁用的 Webhooks#

版本历史

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

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

交付 Headers#

版本历史

• 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 请求中包含以下 headers 到您的端点：

Webhook 正文中的图像 URL 显示#

极狐GitLab 将相对图像引用重写为 webhook 正文中的绝对 URL。

图像 URL 重写示例#

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

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

则在 webhook 正文中的重写图像引用为：

markdown
复制
![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
• 系统 hooks API
• 故障排除