gitlab-webhook（GitLab webhook 开发）

Webhook Skill

Webhook management for GitLab using glab api raw endpoint calls.

Quick Reference

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

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

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

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