GitLab Webhook

POST /webhooks/gitlab

GitLab Webhook

cURL

curl --request POST \
  --url https://api.example.com/webhooks/gitlab \
  --header 'Content-Type: application/json' \
  --header 'X-Gitlab-Token: <x-gitlab-token>' \
  --data '
{
  "object_kind": "<string>",
  "ref": "<string>",
  "after": "<string>",
  "project": {
    "path_with_namespace": "<string>",
    "http_url": "<string>"
  }
}
'

Scan Triggered

{
  "success": true,
  "data": {
    "status": "scan_triggered",
    "scan_id": 42,
    "repo_id": 7,
    "commit_sha": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "ref": "refs/heads/main"
  }
}

Receives GitLab push event webhooks to automatically trigger security scans when code is pushed to repositories.

Authentication

This endpoint is publicly accessible (no API key required) but requires token verification using the configured webhook secret.

Token Verification

GitLab uses simple token-based authentication. The token is sent in the X-Gitlab-Token header:

X-Gitlab-Token: <your_webhook_secret>

The server compares this token with the configured WEBHOOK_SECRET using string equality.

Implementation (see src/routes/webhooks.rs:162):

• Extracts token from X-Gitlab-Token header
• Performs direct string comparison with WEBHOOK_SECRET
• No cryptographic signature computation (unlike GitHub)

Headers

X-Gitlab-Token · string · required

Webhook secret token for authentication

Content-Type · string · default: "application/json"

Request content type

Request Body

GitLab push event payload. Key fields:

object_kind · string · required

Event type. Must be push for the webhook to be processed. Other event types are ignored.

ref · string · required

Git reference that was pushed (e.g., refs/heads/main)

after · string · required

SHA of the commit after the push

project · object · required

Project information

Show properties

path_with_namespace · string · required

Full project path (e.g., group/project)

http_url · string · required

HTTPS clone URL used to match against registered repositories

Example Payload

{
  "object_kind": "push",
  "ref": "refs/heads/main",
  "after": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "project": {
    "path_with_namespace": "acme/web-app",
    "http_url": "https://gitlab.com/acme/web-app.git"
  }
}

Event Handling

1. Token Verification - Validates token against WEBHOOK_SECRET (see src/routes/webhooks.rs:162)
2. Payload Parsing - Deserializes JSON payload (see src/routes/webhooks.rs:168)
3. Event Type Check - Only processes events with object_kind: "push", ignores others (see src/routes/webhooks.rs:180)
4. Repository Lookup - Finds registered repository by http_url (see src/routes/webhooks.rs:218)
5. Scan Creation - Creates a new full scan for the pushed commit (see src/routes/webhooks.rs:245)
6. Pipeline Trigger - Queues or runs scan pipeline (see src/routes/webhooks.rs:265)

Response

success · boolean

Whether the request was successful

data · object

Response data

Show properties

status · string

Request status: scan_triggered or ignored

scan_id · integer

ID of the created scan (only present when status is scan_triggered)

repo_id · integer

ID of the matched repository (only present when status is scan_triggered)

commit_sha · string

SHA of the commit being scanned (only present when status is scan_triggered)

ref · string

Git reference that was pushed (only present when status is scan_triggered)

reason · string

Reason for ignoring the event (only present when status is ignored)

Scan Triggered

{
  "success": true,
  "data": {
    "status": "scan_triggered",
    "scan_id": 42,
    "repo_id": 7,
    "commit_sha": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "ref": "refs/heads/main"
  }
}

Error Responses

401 - Invalid Token

{
  "success": false,
  "error": {
    "code": 401,
    "message": "Invalid token"
  }
}

Configuration

Set the WEBHOOK_SECRET environment variable to enable webhook token verification. This secret must match the secret token configured in your GitLab project webhook settings.

GitLab Webhook Setup

1. Go to your project settings → Webhooks → Add new webhook
2. Set URL to https://your-heimdall-instance.com/api/webhooks/gitlab
3. Set Secret token to match your WEBHOOK_SECRET
4. Under Trigger, select Push events only
5. Ensure Enable SSL verification is checked (recommended)
6. Click Add webhook