How to Test GitLab Webhooks

GitLab Webhook Event Types

GitLab webhooks can be configured at the project level, group level, or system level (self-managed only). Each delivery includes an X-Gitlab-Event header that identifies the event type, and the body contains the full context for that event.

Step 1: Generate a Requex Endpoint

Open requex.me. A unique webhook URL is created for you immediately — no account needed. Copy the URL from the top of the dashboard. It will look like:

https://requex.me/hook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

This URL is publicly reachable over HTTPS — GitLab can send payloads to it without any tunnel or port forwarding.

Step 2: Configure the GitLab Webhook

Navigate to your GitLab project and add the webhook:

1. Go to Project → Settings → Webhooks.
2. Click Add new webhook.
3. Paste your Requex URL into the URL field.
4. Optionally enter a Secret token — GitLab will include this in the X-Gitlab-Token header of every delivery.
5. Select the trigger events you want to test (e.g., Push events, Merge requests events).
6. For testing purposes, you can disable SSL verification — this is safe with Requex since it already uses a valid certificate.
7. Click Add webhook.

Group-level webhooks follow the same flow under Group → Settings → Webhooks and fire for all projects within the group.

Step 3: Trigger a Test Event

The fastest way is to use GitLab's built-in test button. After saving the webhook, scroll down to the webhook in the list and click the Test dropdown next to it. Select any event type (e.g., "Push events") — GitLab sends a sample payload immediately.

To send a real payload, trigger the event naturally:

# Trigger a push event
git commit --allow-empty -m "chore: trigger gitlab webhook test"
git push origin main

For merge request events, open or update a merge request in the GitLab UI. For pipeline events, push a change to a branch that has a .gitlab-ci.yml file.

Step 4: Inspect the Payload

Click the captured request in Requex. The X-Gitlab-Event header tells you the event type. Here is an abbreviated push event payload:

{
  "object_kind": "push",
  "event_name": "push",
  "before": "0000000000000000000000000000000000000000",
  "after": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
  "ref": "refs/heads/main",
  "user_name": "John Doe",
  "project": {
    "id": 15,
    "name": "my-project",
    "web_url": "https://gitlab.com/mygroup/my-project"
  },
  "commits": [
    {
      "id": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7",
      "message": "chore: trigger gitlab webhook test",
      "author": { "name": "John Doe", "email": "john@example.com" }
    }
  ],
  "total_commits_count": 1
}

GitLab also sends your secret token plaintext in the X-Gitlab-Token header — you can see its exact value in the Requex request headers panel, which is useful for confirming your backend is reading the correct header name.

GitLab Token Verification

Unlike GitHub (which uses HMAC), GitLab passes your secret token as a plain string in the X-Gitlab-Token header. Your handler simply compares the header value to your stored secret using a timing-safe comparison:

const crypto = require('crypto');

app.post('/webhooks/gitlab', express.json(), (req, res) => {
  const token = req.headers['x-gitlab-token'];
  const expected = process.env.GITLAB_WEBHOOK_SECRET;

  // Use timing-safe comparison to prevent timing attacks
  if (
    !token ||
    token.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(token), Buffer.from(expected))
  ) {
    return res.status(401).send('Unauthorized');
  }

  const eventType = req.headers['x-gitlab-event'];
  console.log('GitLab event:', eventType);
  console.log('Object kind:', req.body.object_kind);

  res.status(200).send('OK');
});

Note that X-Gitlab-Token is only sent if you configured a secret token when creating the webhook. If you left the secret field blank in GitLab settings, the header will not be present in the delivery.

Common GitLab Webhook Issues