Webhook Management Guide

GitLab Bot offers two approaches for setting up webhooks with your GitLab projects. Choose the method that best fits your organization's needs.

Quick Comparison

Feature Automatic Setup Self-Managed
Setup Time 1 click 5-10 minutes per project
Maintenance Zero - handled automatically Manual updates required
Data Control Flows through GitLab Bot Direct to your endpoint
Token Management Automatic refresh Manual renewal
Security Control Standard OAuth flow Full token custody
Best For Most teams Compliance-sensitive organizations

Which Option Should I Choose?

Choose Automatic Setup if:

  • You want the fastest, simplest setup
  • You trust GitLab Bot to manage tokens securely
  • You have maintainer access on your GitLab projects
  • You prefer zero-maintenance solutions

Choose Self-Managed if:

  • Your organization requires full control over data flow
  • You have specific compliance or audit requirements
  • You want to manage webhook tokens directly
  • You need custom webhook configurations

Automatic Setup (Recommended)

The automatic setup provides a seamless, one-click experience that handles all webhook configuration for you.

How It Works

  1. OAuth Authorization: You grant GitLab Bot API access to your GitLab account
  2. Project Discovery: GitLab Bot automatically finds projects where you have maintainer access
  3. Webhook Creation: GitLab Bot creates and configures webhooks with proper security tokens
  4. Token Management: GitLab Bot handles token refresh and webhook maintenance automatically

Setup Instructions

  1. Navigate to Settings in GitLab Bot
  2. Find the GitLab Integration card
  3. Click "Set Up" to start the automatic setup process
  4. Authorize GitLab Bot when redirected to GitLab
  5. Select which projects to set up webhooks for
  6. Done! Webhooks are configured automatically

Self-Managed Webhooks

Self-managed webhooks give you complete control over the setup and maintenance of your webhook configuration.

Trade-offs to Consider

  • • Manual setup required for each project
  • • You handle token renewal and webhook updates
  • • Responsible for troubleshooting webhook delivery issues
  • • Complete control and data sovereignty

Setup Instructions

Step 1: Enable Self-Management

  1. Go to Settings in GitLab Bot
  2. Find the "GitLab Integration" section
  3. Click "I'll set this up myself"
  4. Confirm you want to manage webhooks manually

Step 2: Configure GitLab Webhooks

For each GitLab project you want to integrate:

  1. Navigate to your GitLab project → Settings → Webhooks
  2. Add new webhook with:
    • URL: https://your-gitlabbot-instance.com/inbound/gitlab/YOUR_WEBHOOK_ID
    • Secret Token: Use the token provided in GitLab Bot settings
    • Trigger Events: Push events, Merge request events, Pipeline events, Issues events
  3. Click "Add webhook"
  4. Test the webhook using GitLab's test feature

Switching Between Options

Enable Self-Management

Switch from automatic to self-managed:

  1. Go to Settings
  2. Click "I'll set this up myself"
  3. Existing webhooks continue working
  4. Follow self-managed setup instructions

Return to Automatic

Switch from self-managed to automatic:

  1. Go to Settings
  2. Click "Enable setup prompts"
  3. Click "Set Up" button
  4. Remove manual webhooks from GitLab

Note: Switching between modes does not affect your existing webhook data or message history.

Troubleshooting

Automatic Setup Issues

  • Permission Errors: Ensure you have maintainer access on GitLab projects
  • OAuth Failures: Check that GitLab Bot is authorized in your GitLab account
  • Missing Projects: Projects appear only if you have maintainer permissions

Self-Managed Issues

  • Webhook Delivery Failures: Check GitLab's webhook logs for error details
  • Token Mismatches: Verify secret tokens match between GitLab and GitLab Bot
  • Missing Events: Ensure correct trigger events are selected in GitLab

FAQ

Can I use both automatic and self-managed for different projects?

No, the setting applies to your entire account. You can switch between modes, but all projects will use the same approach.

Will switching modes affect my message history?

No, your existing Slack messages and merge request history are preserved when switching between webhook management modes.

Is there a performance difference between the two approaches?

Both approaches deliver similar performance. Automatic setup may have slightly faster initial setup, while self-managed gives you more control over webhook configuration.

← Back to Documentation