Webhook Configuration

Webhooks allow GitLab to send real-time notifications to GitLab Bot when events occur in your repositories.

What Are Webhooks?

Webhooks are HTTP callbacks that GitLab sends to your application when specific events happen. GitLab Bot uses webhooks to:

  • Receive merge request updates
  • Track pipeline status
  • Monitor issue changes
  • Capture comments and reviews

Setting Up Webhooks

1. Get Your Webhook URL

Find your unique webhook URL in the dashboard:

https://your-app.example.com/webhooks/gitlab/{customer_id}

2. Add Webhook to GitLab

In your GitLab project:

  1. Go to Settings → Webhooks
  2. Paste your webhook URL
  3. Enter a Secret Token (required for security)
  4. Select trigger events
  5. Click Add webhook

3. Select Events

Choose which events should trigger notifications:

Recommended Events

  • ✅ Push events
  • ✅ Merge request events
  • ✅ Pipeline events
  • ✅ Issue events
  • ✅ Note events (comments)

Optional Events

  • Job events
  • Wiki page events
  • Deployment events
  • Release events

Security Best Practices

Use Secret Tokens

Always set a secret token to verify webhook authenticity:

# GitLab Bot verifies this token automatically

defp verify_webhook(conn, secret) do

  header_token = get_req_header(conn, "x-gitlab-token")

  Plug.Crypto.secure_compare(header_token, secret)

end

Enable SSL Verification

Ensure Enable SSL verification is checked in GitLab webhook settings.

Restrict IP Addresses

If possible, configure your firewall to only accept requests from GitLab's IP ranges.

Testing Webhooks

Manual Testing

Use GitLab's webhook test feature:

  1. Go to your webhook in GitLab settings
  2. Click Test next to the webhook
  3. Select an event type
  4. Check the response

Viewing Webhook Logs

Monitor webhook activity in the dashboard:

  • View recent deliveries
  • Check response codes
  • Inspect payload data
  • Debug failed webhooks

Common Events

Merge Request Events

Triggered when merge requests are:

  • Created
  • Updated
  • Merged
  • Closed
  • Reopened

Example payload:

{

  "object_kind": "merge_request",

  "event_type": "merge_request",

  "user": {

    "name": "Administrator",

    "username": "root"

  },

  "object_attributes": {

    "id": 99,

    "target_branch": "main",

    "source_branch": "feature-branch",

    "title": "Add new feature",

    "state": "opened"

  }

}

Pipeline Events

Triggered on pipeline status changes:

  • Created
  • Running
  • Success
  • Failed
  • Canceled

Note Events

Triggered when comments are added to:

  • Merge requests
  • Issues
  • Commits
  • Snippets

Troubleshooting

Webhook Fails to Deliver

Possible causes:

  1. Incorrect URL: Verify the webhook URL is correct
  2. Network issues: Check firewall and DNS settings
  3. SSL errors: Ensure valid SSL certificate
  4. Timeout: Webhook endpoint must respond within 10 seconds

Authentication Failures

If webhooks are being rejected:

  1. Verify secret token matches
  2. Check that token is being sent in X-Gitlab-Token header
  3. Review webhook logs for specific error messages

Missing Events

If expected events aren't being received:

  1. Confirm event type is selected in GitLab webhook settings
  2. Check that event meets any configured filters
  3. Verify webhook is active (not disabled)

Advanced Configuration

Webhook Filters

Filter events based on branches:

Push events: main, develop, release/*

Custom Headers

Add custom headers for advanced routing or authentication.

Webhook Groups

Configure different webhooks for different event types to separate concerns.

API Reference

For detailed information about webhook payloads, see:

Next Steps