gitlab-webhook

name	gitlab-webhook
description	GitLab webhook operations via API. ALWAYS use this skill when user wants to: (1) list/view webhooks, (2) create/update/delete webhooks, (3) configure webhook events, (4) test webhook delivery.
version	1.0.0
author	GitLab-Assistant-Skills
license	MIT
allowed-tools	["Bash","Read","Glob","Grep"]

Webhook Skill

Webhook management for GitLab using glab api raw endpoint calls.

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

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)

API Prerequisites

Required Token Scopes: api

Permissions:

• View webhooks: Maintainer+
• Manage webhooks: Maintainer+

Webhook Events

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

Available Commands

List Webhooks

# 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"

Get Webhook Details

# Get specific webhook
glab api projects/123/hooks/789 --method GET

Create Webhook

# 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"

Update Webhook

# 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

Delete Webhook

# Delete webhook
glab api projects/123/hooks/789 --method DELETE

Test Webhook

# 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

Webhook Configuration Options

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

Common Workflows

Workflow 1: Set Up Slack Notifications

# 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

Workflow 2: Set Up CI Trigger

# 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"

Workflow 3: Audit All Webhooks

# 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"'

Workflow 4: Migrate Webhook to New URL

# 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

Workflow 5: Set Up Deployment Notifications

# 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"

Workflow 6: Disable All Non-Essential Events

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

Webhook Payload

GitLab sends JSON payloads with event data. Key fields:

Push Event Payload

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

MR Event Payload

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

Validating Webhooks

Use the secret token to validate webhook authenticity:

# In your webhook handler, verify the X-Gitlab-Token header
# matches the token you configured

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

Best Practices

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

Related Documentation

• API Helpers
• Safeguards
• Quick Reference
• GitLab Webhooks API