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

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

"gitlab-webhook"