gitlab-webhook
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.
How do I install this agent skill?
npx skills add https://github.com/grandcamel/gitlab-assistant-skills --skill gitlab-webhookIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides legitimate and well-documented utility for managing GitLab webhooks using the glab CLI tool. It includes standard patterns for creating, listing, and testing webhooks without any detected malicious behaviors such as exfiltration, persistence, or obfuscation.
- Socketpass
No alerts
- Snykfail
Risk: HIGH · No issues
- Runlayerwarn
1/1 file flagged
- ZeroLeakspass
1 finding · Score: 82/100
What does this agent skill do?
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
Related Documentation
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/grandcamel/gitlab-assistant-skills/gitlab-webhook">View gitlab-webhook on skillZs</a>