Webhooks

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

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

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

Webhook 事件

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

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

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

Webhook 限制

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

• 每个项目或群组最多可配置的 webhook 数量。
• 每分钟 webhook 调用次数。
• webhook 超时持续时间。

对于 GitLab Self-Managed，管理员可以修改这些限制。

群组 Webhooks

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

群组 webhook 事件类型

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

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

同时在项目和群组中配置的 webhooks

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

配置 webhooks

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

创建 webhook

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

先决条件：

• 对于项目 webhooks，您必须拥有项目的 Maintainer（维护者）角色或更高权限。
• 对于群组 webhooks，您必须拥有群组的 Owner（所有者）角色。

要创建 webhook：

1. 在左侧边栏，选择 Search or go to 并找到您的项目或群组。
2. 选择 Settings > Webhooks。
3. 选择 Add new webhook。
4. 在 URL 中，输入 webhook 端点的 URL。 对特殊字符使用百分号编码。
5. 可选。为 webhook 输入 Name 和 Description。
6. 可选。在 Secret token 中，输入用于验证请求的令牌。
7. 在 Trigger 部分，选择触发 webhook 的 事件。
8. 可选。要禁用 SSL 验证，取消勾选 Enable SSL verification 复选框。
9. 选择 Add webhook。

secret token 会通过 X-Gitlab-Token HTTP 头随 webhook 请求一起发送。 您的 webhook 端点可以使用此令牌来验证请求的合法性。

遮蔽 webhook URL 的敏感部分

遮蔽 webhook URL 的敏感部分以增强安全性。 当执行 webhooks 时，遮蔽部分会被替换为配置的值，不会被记录，并且在数据库中静态加密。

要遮蔽 webhook URL 的敏感部分：

1. 在左侧边栏，选择 Search or go to 并找到您的项目或群组。
2. 选择 Settings > Webhooks。
3. 在 URL 中，输入 webhook 的完整 URL。
4. 要定义遮蔽部分，选择 Add URL masking。
5. 在 Sensitive portion of URL 中，输入您要遮蔽的 URL 部分。
6. 在 How it looks in the UI 中，输入要显示在遮蔽部分替代值的值。 变量名必须只包含小写字母（a-z）、数字（0-9）或下划线（_）。
7. 选择 Save changes。

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

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

自定义标头

向 webhook 请求添加自定义标头，用于外部服务的身份验证。 每个 webhook 最多可以配置 20 个自定义标头。

自定义标头必须：

• 不能覆盖 传递标头 的值。
• 只能包含字母数字字符、句点、连字符或下划线。
• 必须以字母开头，以字母或数字结尾。
• 不能有连续的句点、连字符或下划线。

自定义标头在 Recent events 中显示为遮蔽值。

自定义 webhook 模板

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

创建自定义 webhook 模板

• 对于项目 webhooks，您必须拥有项目的 Maintainer（维护者）角色或更高权限。
• 对于群组 webhooks，您必须拥有群组的 Owner（所有者）角色。

要创建自定义 webhook 模板：

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

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

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

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

自定义 webhook 模板示例

对于这个自定义负载模板：

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

push 事件的请求负载结果为：

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

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

按分支过滤推送事件

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

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

使用通配符模式

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

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

使用正则表达式

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

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

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

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

配置 webhooks 以支持相互 TLS

通过设置 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 请求历史

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

先决条件：

• 对于项目 webhooks，您必须拥有项目的 Maintainer（维护者）角色或更高权限。
• 对于群组 webhooks，您必须拥有群组的 Owner（所有者）角色。

要查看 webhook 的请求历史：

1. 在左侧边栏，选择 Search or go to 并找到您的项目或群组。
2. 选择 Settings > Webhooks。
3. 选择要查看的 webhook 的 Edit。
4. 转到 Recent events 部分。

Recent events 部分显示过去两天内对 webhook 的所有请求。 表格包括：

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

检查请求和响应详情

先决条件：

• 对于项目 webhooks，您必须拥有项目的 Maintainer（维护者）角色或更高权限。
• 对于群组 webhooks，您必须拥有群组的 Owner（所有者）角色。

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

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

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

1. 在左侧边栏，选择 Search or go to 并找到您的项目或群组。
2. 选择 Settings > Webhooks。
3. 选择要查看的 webhook 的 Edit。
4. 转到 Recent events 部分。
5. 选择事件的 View details。

要使用相同的数据和相同的 Idempotency-Key 标头 重新发送请求，选择 Resend Request。 如果 webhook URL 已更改，您无法重新发送请求。 有关以编程方式重新发送的信息，请参阅我们的 API 文档。

测试 webhook

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

先决条件：

• 对于项目 webhooks，您必须拥有项目的 Maintainer（维护者）角色或更高权限。
• 对于群组 webhooks，您必须拥有群组的 Owner（所有者）角色。
• 要测试 push events，您的项目必须至少有一个提交。

要测试 webhook：

1. 在左侧边栏，选择 Search or go to 并找到您的项目或群组。
2. 选择 Settings > Webhooks。
3. 在已配置的 webhook 列表中，找到您要测试的 webhook。
4. 从 Test 下拉列表中，选择要测试的事件类型。

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

项目 webhook 和群组 webhook 的某些事件类型不支持测试。 有关更多信息，请参阅 issue 379201。

Webhook 参考

使用此技术参考来：

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

Webhook 接收器要求

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

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

要优化您的 webhook 接收器：

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

自动禁用的 webhooks

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

要查看自动禁用的 webhooks：

1. 在左侧边栏，选择 Search or go to 并找到您的项目或群组。
2. 选择 Settings > Webhooks。

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

• Temporarily disabled 表示 临时禁用 的 webhooks
• Disabled 表示 永久禁用 的 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 在 Recent events 中可能显示四次失败， 即使 UI 可能显示它们有 40 次失败。

重新启用禁用的 webhooks

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

传递标头

GitLab 在发送到您端点的 webhook 请求中包含以下标头：

Webhook 正文中的图像 URL 显示

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

图像 URL 重写示例

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

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

webhook 正文中的重写图像引用将是：

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

此示例假设：

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

图像 URL 重写的例外情况

当以下情况时，GitLab 不会重写图像 URL：

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

相关主题

• Webhook 事件和 webhook JSON 负载
• 项目 webhooks API
• 群组 webhooks API
• 系统 webhooks API
• 故障排除
• 使用 webhooks 和 Twilio 发送 SMS 警报
• 自动应用 GitLab 标签