Webhook Skill

Webhook技能

Webhook management for GitLab using

glab api

raw endpoint calls.

使用

glab api

原始端点调用进行GitLab Webhook管理。

Quick Reference

快速参考

Operation	Command Pattern	Risk
List webhooks	`glab api projects/:id/hooks`	-
Get webhook	`glab api projects/:id/hooks/:hook_id`	-
Create webhook	`glab api projects/:id/hooks -X POST -f ...`	⚠️
Update webhook	`glab api projects/:id/hooks/:hook_id -X PUT -f ...`	⚠️
Delete webhook	`glab api projects/:id/hooks/:hook_id -X DELETE`	⚠️⚠️
Test webhook	`glab api projects/:id/hooks/:hook_id/test/:trigger -X POST`	⚠️
List group hooks	`glab api groups/:id/hooks`	-

Risk Legend: - Safe | ⚠️ Caution | ⚠️⚠️ Warning | ⚠️⚠️⚠️ Danger

操作	命令格式	风险
列出Webhook	`glab api projects/:id/hooks`	-
获取Webhook详情	`glab api projects/:id/hooks/:hook_id`	-
创建Webhook	`glab api projects/:id/hooks -X POST -f ...`	⚠️
更新Webhook	`glab api projects/:id/hooks/:hook_id -X PUT -f ...`	⚠️
删除Webhook	`glab api projects/:id/hooks/:hook_id -X DELETE`	⚠️⚠️
测试Webhook	`glab api projects/:id/hooks/:hook_id/test/:trigger -X POST`	⚠️
列出组Webhook	`glab api groups/:id/hooks`	-

风险说明：- 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

When to Use This Skill

何时使用此技能

ALWAYS use when:

User mentions "webhook", "hook", "web hook"
User wants to integrate GitLab with external services
User mentions "notification", "callback", "trigger URL"
User wants to set up CI/CD integrations or Slack notifications

NEVER use when:

User wants to configure built-in integrations (use project settings)
User wants to manage CI/CD pipelines (use gitlab-ci)
User wants system hooks (requires admin access)

请务必在以下场景使用：

用户提及“webhook”、“hook”、“web hook”
用户希望将GitLab与外部服务集成
用户提及“通知”、“回调”、“触发URL”
用户希望设置CI/CD集成或Slack通知

请勿在以下场景使用：

用户希望配置内置集成（请使用项目设置）
用户希望管理CI/CD流水线（请使用gitlab-ci）
用户需要系统级Webhook（需要管理员权限）

API Prerequisites

API前置条件

Required Token Scopes:

api

Permissions:

View webhooks: Maintainer+
Manage webhooks: Maintainer+

所需Token权限范围：

api

权限要求：

查看Webhook：维护者及以上权限
管理Webhook：维护者及以上权限

Webhook Events

Webhook事件

Event	Flag	Description
Push	`push_events`	Code pushed to repository
Tag	`tag_push_events`	Tags created/deleted
Merge Request	`merge_requests_events`	MR created/updated/merged
Issues	`issues_events`	Issue created/updated/closed
Notes	`note_events`	Comments on MRs/issues/commits
Confidential Notes	`confidential_note_events`	Confidential comments
Job	`job_events`	CI job status changes
Pipeline	`pipeline_events`	Pipeline status changes
Deployment	`deployment_events`	Deployment status changes
Wiki	`wiki_page_events`	Wiki pages created/updated
Releases	`releases_events`	Releases created

事件	参数标识	描述
代码推送	`push_events`	代码推送到仓库时触发
标签推送	`tag_push_events`	标签创建/删除时触发
合并请求	`merge_requests_events`	合并请求创建/更新/合并时触发
问题	`issues_events`	问题创建/更新/关闭时触发
评论	`note_events`	对合并请求/问题/提交的评论触发
私密评论	`confidential_note_events`	私密评论触发
作业	`job_events`	CI作业状态变更时触发
流水线	`pipeline_events`	流水线状态变更时触发
部署	`deployment_events`	部署状态变更时触发
维基页面	`wiki_page_events`	维基页面创建/更新时触发
版本发布	`releases_events`	版本发布创建时触发

Available Commands

可用命令

List Webhooks

列出Webhook

bash

undefined

bash

undefined

List project webhooks

glab api projects/123/hooks --method GET

List with pagination

glab api projects/123/hooks --paginate

List group webhooks (Premium)

glab api groups/456/hooks --method GET

Using project path

glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/hooks"

undefined

glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/hooks"

undefined

Get Webhook Details

获取Webhook详情

bash

undefined

bash

undefined

Get specific webhook

glab api projects/123/hooks/789 --method GET

undefined

glab api projects/123/hooks/789 --method GET

undefined

Create Webhook

创建Webhook

bash

undefined

bash

undefined

Basic webhook for push events

glab api projects/123/hooks --method POST
-f url="https://example.com/webhook"
-f push_events=true

Webhook for MR and pipeline events

glab api projects/123/hooks --method POST
-f url="https://example.com/webhook"
-f push_events=false
-f merge_requests_events=true
-f pipeline_events=true

Webhook with secret token

glab api projects/123/hooks --method POST
-f url="https://example.com/webhook"
-f push_events=true
-f token="my-secret-token"
-f enable_ssl_verification=true

Full-featured webhook

glab api projects/123/hooks --method POST
-f url="https://example.com/webhook"
-f push_events=true
-f tag_push_events=true
-f merge_requests_events=true
-f issues_events=true
-f note_events=true
-f pipeline_events=true
-f job_events=true
-f token="secret"
-f enable_ssl_verification=true

Webhook for specific branches only

glab api projects/123/hooks --method POST
-f url="https://example.com/webhook"
-f push_events=true
-f push_events_branch_filter="main"

undefined

glab api projects/123/hooks --method POST
-f url="https://example.com/webhook"
-f push_events=true
-f push_events_branch_filter="main"

undefined

Update Webhook

更新Webhook

bash

undefined

bash

undefined

Update URL

glab api projects/123/hooks/789 --method PUT
-f url="https://new-url.com/webhook"

Enable additional events

glab api projects/123/hooks/789 --method PUT
-f pipeline_events=true
-f job_events=true

Disable event

glab api projects/123/hooks/789 --method PUT
-f push_events=false

Update secret token

glab api projects/123/hooks/789 --method PUT
-f token="new-secret-token"

Change SSL verification

glab api projects/123/hooks/789 --method PUT
-f enable_ssl_verification=false

undefined

glab api projects/123/hooks/789 --method PUT
-f enable_ssl_verification=false

undefined

Delete Webhook

删除Webhook

bash

undefined

bash

undefined

Delete webhook

glab api projects/123/hooks/789 --method DELETE

undefined

glab api projects/123/hooks/789 --method DELETE

undefined

Test Webhook

测试Webhook

bash

undefined

bash

undefined

Test push event

glab api projects/123/hooks/789/test/push_events --method POST

Test MR event

glab api projects/123/hooks/789/test/merge_requests_events --method POST

Test tag push event

glab api projects/123/hooks/789/test/tag_push_events --method POST

Test note event

glab api projects/123/hooks/789/test/note_events --method POST

Test issues event

glab api projects/123/hooks/789/test/issues_events --method POST

undefined

glab api projects/123/hooks/789/test/issues_events --method POST

undefined

Webhook Configuration Options

Webhook配置选项

Option	Type	Description
`url`	string	Webhook endpoint URL (required)
`token`	string	Secret token for validation
`push_events`	boolean	Trigger on push
`push_events_branch_filter`	string	Branch filter for push events
`tag_push_events`	boolean	Trigger on tag push
`merge_requests_events`	boolean	Trigger on MR events
`issues_events`	boolean	Trigger on issue events
`confidential_issues_events`	boolean	Trigger on confidential issues
`note_events`	boolean	Trigger on comments
`confidential_note_events`	boolean	Trigger on confidential notes
`pipeline_events`	boolean	Trigger on pipeline events
`job_events`	boolean	Trigger on job events
`deployment_events`	boolean	Trigger on deployments
`wiki_page_events`	boolean	Trigger on wiki changes
`releases_events`	boolean	Trigger on releases
`enable_ssl_verification`	boolean	Verify SSL certificate

选项	类型	描述
`url`	string	Webhook端点URL（必填）
`token`	string	用于验证的密钥令牌
`push_events`	boolean	代码推送时触发
`push_events_branch_filter`	string	代码推送事件的分支过滤器
`tag_push_events`	boolean	标签推送时触发
`merge_requests_events`	boolean	合并请求事件触发
`issues_events`	boolean	问题事件触发
`confidential_issues_events`	boolean	私密问题事件触发
`note_events`	boolean	评论事件触发
`confidential_note_events`	boolean	私密评论事件触发
`pipeline_events`	boolean	流水线事件触发
`job_events`	boolean	作业事件触发
`deployment_events`	boolean	部署事件触发
`wiki_page_events`	boolean	维基页面事件触发
`releases_events`	boolean	版本发布事件触发
`enable_ssl_verification`	boolean	验证SSL证书

Common Workflows

常见工作流

Workflow 1: Set Up Slack Notifications

工作流1：设置Slack通知

bash

undefined

bash

undefined

Create webhook for Slack

glab api projects/123/hooks --method POST
-f url="https://hooks.slack.com/services/T00/B00/XXX"
-f push_events=true
-f merge_requests_events=true
-f pipeline_events=true
-f enable_ssl_verification=true

undefined

glab api projects/123/hooks --method POST
-f url="https://hooks.slack.com/services/T00/B00/XXX"
-f push_events=true
-f merge_requests_events=true
-f pipeline_events=true
-f enable_ssl_verification=true

undefined

Workflow 2: Set Up CI Trigger

工作流2：设置CI触发器

bash

undefined

bash

undefined

Webhook to trigger external CI

glab api projects/123/hooks --method POST
-f url="https://ci.example.com/trigger"
-f push_events=true
-f tag_push_events=true
-f token="ci-trigger-token"
-f push_events_branch_filter="main"

undefined

glab api projects/123/hooks --method POST
-f url="https://ci.example.com/trigger"
-f push_events=true
-f tag_push_events=true
-f token="ci-trigger-token"
-f push_events_branch_filter="main"

undefined

Workflow 3: Audit All Webhooks

工作流3：审计所有Webhook

bash

undefined

bash

undefined

List all webhooks with details

glab api projects/123/hooks --paginate |
jq -r '.[] | "ID: (.id)\n URL: (.url)\n Events: push=(.push_events), mr=(.merge_requests_events), pipeline=(.pipeline_events)\n SSL: (.enable_ssl_verification)\n"'

undefined

glab api projects/123/hooks --paginate |
jq -r '.[] | "ID: (.id)\n URL: (.url)\n Events: push=(.push_events), mr=(.merge_requests_events), pipeline=(.pipeline_events)\n SSL: (.enable_ssl_verification)\n"'

undefined

Workflow 4: Migrate Webhook to New URL

工作流4：迁移Webhook到新URL

bash

undefined

bash

undefined

1. Get current webhook config

glab api projects/123/hooks/789 | jq

2. Update URL

glab api projects/123/hooks/789 --method PUT
-f url="https://new-service.example.com/webhook"

3. Test the webhook

glab api projects/123/hooks/789/test/push_events --method POST

undefined

glab api projects/123/hooks/789/test/push_events --method POST

undefined

Workflow 5: Set Up Deployment Notifications

工作流5：设置部署通知

bash

undefined

bash

undefined

Webhook for deployment events only

glab api projects/123/hooks --method POST
-f url="https://deploy-tracker.example.com/webhook"
-f push_events=false
-f deployment_events=true
-f token="deploy-secret"

undefined

glab api projects/123/hooks --method POST
-f url="https://deploy-tracker.example.com/webhook"
-f push_events=false
-f deployment_events=true
-f token="deploy-secret"

undefined

Workflow 6: Disable All Non-Essential Events

工作流6：禁用所有非必要事件

bash

hook_id=789

bash

hook_id=789

Keep only push and MR events

glab api projects/123/hooks/$hook_id --method PUT
-f push_events=true
-f merge_requests_events=true
-f tag_push_events=false
-f issues_events=false
-f note_events=false
-f job_events=false
-f pipeline_events=false

undefined

glab api projects/123/hooks/$hook_id --method PUT
-f push_events=true
-f merge_requests_events=true
-f tag_push_events=false
-f issues_events=false
-f note_events=false
-f job_events=false
-f pipeline_events=false

undefined

Webhook Payload

Webhook负载

GitLab sends JSON payloads with event data. Key fields:

GitLab会发送包含事件数据的JSON负载。关键字段：

Push Event Payload

代码推送事件负载

json

{
  "object_kind": "push",
  "ref": "refs/heads/main",
  "before": "abc123...",
  "after": "def456...",
  "commits": [...],
  "project": {...}
}

json

{
  "object_kind": "push",
  "ref": "refs/heads/main",
  "before": "abc123...",
  "after": "def456...",
  "commits": [...],
  "project": {...}
}

MR Event Payload

合并请求事件负载

json

{
  "object_kind": "merge_request",
  "event_type": "merge_request",
  "object_attributes": {
    "iid": 1,
    "title": "...",
    "state": "opened",
    "action": "open"
  }
}

json

{
  "object_kind": "merge_request",
  "event_type": "merge_request",
  "object_attributes": {
    "iid": 1,
    "title": "...",
    "state": "opened",
    "action": "open"
  }
}

Validating Webhooks

验证Webhook

Use the secret token to validate webhook authenticity:

bash

undefined

使用密钥令牌验证Webhook的真实性：

bash

undefined

In your webhook handler, verify the X-Gitlab-Token header

matches the token you configured

undefined

undefined

Troubleshooting

故障排查

Issue	Cause	Solution
Webhook not firing	Event not enabled	Check event flags
403 Forbidden	Not maintainer	Need Maintainer+ role
SSL verification failed	Invalid certificate	Use `enable_ssl_verification=false` or fix cert
Webhook URL unreachable	Network/firewall issue	Verify URL is accessible from GitLab
Test returns error	Endpoint error	Check your webhook handler logs
Too many requests	Webhook loop	Verify handler doesn't trigger events

问题	原因	解决方案
Webhook未触发	事件未启用	检查事件参数标识
403 禁止访问	无维护者权限	需要维护者及以上角色
SSL验证失败	证书无效	使用 `enable_ssl_verification=false` 或修复证书
Webhook URL无法访问	网络/防火墙问题	验证GitLab能否访问该URL
测试返回错误	端点错误	检查Webhook处理程序日志
请求过于频繁	Webhook循环	验证处理程序不会触发重复事件

Best Practices

最佳实践

Use HTTPS: Always use secure URLs for webhooks
Set secret token: Validate webhooks with a secret token
Enable only needed events: Reduce noise and processing
Handle failures gracefully: GitLab retries failed deliveries
Monitor webhook health: Check recent deliveries in GitLab UI
Use branch filters: Limit push events to relevant branches

使用HTTPS：始终为Webhook使用安全URL
设置密钥令牌：使用密钥令牌验证Webhook
仅启用所需事件：减少冗余和处理量
优雅处理失败：GitLab会重试失败的交付
监控Webhook健康状态：在GitLab UI中检查近期交付记录
使用分支过滤器：将推送事件限制到相关分支

gitlab-webhook

Original

Translation

Webhook Skill

Webhook技能

Quick Reference

快速参考

When to Use This Skill

何时使用此技能

API Prerequisites

API前置条件

Webhook Events

Webhook事件

Available Commands

可用命令

List Webhooks

列出Webhook

List project webhooks

List project webhooks

List with pagination

List with pagination

List group webhooks (Premium)

List group webhooks (Premium)

Using project path

Using project path

Get Webhook Details

获取Webhook详情

Get specific webhook

Get specific webhook

Create Webhook

创建Webhook

Basic webhook for push events

Basic webhook for push events

Webhook for MR and pipeline events

Webhook for MR and pipeline events

Webhook with secret token

Webhook with secret token

Full-featured webhook

Full-featured webhook

Webhook for specific branches only

Webhook for specific branches only

Update Webhook

更新Webhook

Update URL

Update URL

Enable additional events

Enable additional events

Disable event

Disable event

Update secret token

Update secret token

Change SSL verification

Change SSL verification

Delete Webhook

删除Webhook

Delete webhook

Delete webhook

Test Webhook

测试Webhook

Test push event

Test push event

Test MR event

Test MR event

Test tag push event

Test tag push event

Test note event

Test note event

Test issues event

Test issues event

Webhook Configuration Options

Webhook配置选项

Common Workflows

常见工作流

Workflow 1: Set Up Slack Notifications

工作流1：设置Slack通知

Create webhook for Slack

Create webhook for Slack

Workflow 2: Set Up CI Trigger

工作流2：设置CI触发器

Webhook to trigger external CI