GitLab Integration

Set up HookWatch to receive GitLab webhooks for repository events like pushes, merge requests, pipelines, and releases.

Prerequisites

  • A HookWatch account
  • A GitLab project with Maintainer access or higher
  • A server endpoint to process webhook payloads

Step 1: Create a HookWatch endpoint

  1. Go to your Endpoints page
  2. Click "Create Endpoint"
  3. Enter a name like "GitLab Webhooks"
  4. Enter your destination URL (where you want webhooks forwarded)
  5. Copy the generated webhook URL

Your HookWatch URL will look like:

https://hook.hookwatch.dev/wh/abc123xyz

Step 2: Configure GitLab webhooks

For a project:

  1. Go to your project on GitLab
  2. Click Settings > Webhooks
  3. Paste your HookWatch URL in the "URL" field
  4. Enter a Secret token (used to verify webhooks)
  5. Select the trigger events you want
  6. Click "Add webhook"

For a group:

  1. Go to your group settings on GitLab
  2. Click Webhooks in the sidebar
  3. Follow the same steps as above

Common trigger events:

Push events
Merge request events
Pipeline events
Tag push events
Issue events
Release events
Deployment events
Note (comment) events

Step 3: Verify webhooks on your server

GitLab sends a secret token in the X-Gitlab-Token header. HookWatch forwards this header so you can verify the webhook by comparing it to your stored secret.

Node.js / Express

Note

Unlike GitHub and Stripe which use HMAC signatures, GitLab uses a simple secret token comparison. The token is sent as a plain header value.

GitLab webhook headers

HookWatch forwards all GitLab headers. Here are the important ones:

HeaderDescription
X-Gitlab-EventThe event type (Push Hook, Merge Request Hook, etc.)
X-Gitlab-TokenSecret token for verification
X-Gitlab-Event-UUIDUnique ID for the webhook delivery
X-Gitlab-InstanceThe GitLab instance URL

Testing the integration

You can test GitLab webhooks by:

  1. Go to your webhook settings and click "Test" next to any event type
  2. Push a commit or create a merge request
  3. Check your HookWatch Events page to see the events

Common issues

Token verification fails

Ensure the secret token in your code exactly matches what you entered in GitLab settings. The token is case-sensitive.

Webhook shows SSL error

If using self-hosted GitLab, make sure "Enable SSL verification" is checked. HookWatch endpoints always support SSL.

Missing pipeline events

Pipeline events are only sent for pipelines triggered by pushes, merge requests, or API calls. Scheduled pipelines may need a separate webhook configuration.