Skip to main content
POST
/
webhooks
/
gitlab
GitLab Webhook
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>"
  }
}
'
{
  "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

​
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
{
  "success": true,
  "data": {
    "status": "scan_triggered",
    "scan_id": 42,
    "repo_id": 7,
    "commit_sha": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "ref": "refs/heads/main"
  }
}

​
Error Responses

{
  "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

Build docs developers (and LLMs) love

Get started for freeTalk to us