Skip to main content

Configure GitLab to Send Webhooks

Configure GitLab project or group webhooks to send event notifications to Harness AI SRE for deployments, pipelines, and security alerts.

Before you begin​

  • Harness webhook endpoint: Create a GitLab webhook in Harness AI SRE using the GitLab webhook template.
  • GitLab permissions: Maintainer or Owner role for the project/group.
  • Webhook URL: Copy the webhook URL from your Harness webhook configuration.
  • GitLab webhooks documentation: Go to Webhooks for webhook configuration guide.
  • Webhook events reference: Go to Webhook Events for event-specific payload structures.

Create project webhook​

  1. Go to your GitLab project
  2. Click Settings → Webhooks
  3. Expand Add new webhook

Configure webhook​

  • URL: Your Harness webhook URL 
    https://<your-harness-instance>/gateway/ai-sre/api/webhooks/<webhook-id>
  • Secret token: (Optional) Sent as plain text for token comparison, not cryptographic signature verification
  • Trigger: Select events to trigger webhook
  • SSL verification: Enable SSL verification

Test webhook​

Click Test → Select event type → Click Test button

GitLab sends a test payload to verify the webhook is reachable.

Add webhook​

Click Add webhook to save.

Configure field mapping in Harness​

GitLab webhook payload structure​

{
  "object_kind": "pipeline",
  "object_attributes": {
    "id": 123,
    "ref": "main",
    "tag": false,
    "sha": "abc123def456",
    "before_sha": "def456abc123",
    "source": "push",
    "status": "failed",
    "detailed_status": "failed",
    "stages": ["build", "test", "deploy"],
    "created_at": "2025-07-01 10:30:00 UTC",
    "finished_at": "2025-07-01 10:35:00 UTC",
    "duration": 300,
    "variables": []
  },
  "user": {
    "name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com"
  },
  "project": {
    "id": 456,
    "name": "my-app",
    "description": "My application",
    "web_url": "https://gitlab.com/mygroup/my-app",
    "path_with_namespace": "mygroup/my-app"
  },
  "commit": {
    "id": "abc123def456",
    "message": "Fix production bug",
    "title": "Fix production bug",
    "timestamp": "2025-07-01T10:30:00Z",
    "url": "https://gitlab.com/mygroup/my-app/-/commit/abc123def456",
    "author": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  },
  "builds": [
    {
      "id": 789,
      "stage": "deploy",
      "name": "deploy_production",
      "status": "failed",
      "created_at": "2025-07-01 10:33:00 UTC",
      "started_at": "2025-07-01 10:33:05 UTC",
      "finished_at": "2025-07-01 10:35:00 UTC",
      "when": "on_success",
      "manual": false,
      "allow_failure": false,
      "user": {
        "name": "John Doe",
        "username": "johndoe",
        "email": "john@example.com"
      },
      "runner": null,
      "environment": {
        "name": "production",
        "action": "start"
      }
    }
  ]
}

Field mapping by event type​

title: "Pipeline " + webhook.object_attributes.status + ": " + webhook.project.path_with_namespace
message: "Pipeline for " + webhook.object_attributes.ref + " " + webhook.object_attributes.status + "\n\n" +
         "Commit: " + webhook.commit.title + "\n" +
         "Author: " + webhook.user.name + "\n" +
         "Duration: " + string(webhook.object_attributes.duration) + "s"

severity: webhook.object_attributes.status == "failed" ? "critical" :
          webhook.object_attributes.status == "canceled" ? "medium" : "info"

source: "gitlab"
link: webhook.project.web_url + "/-/pipelines/" + string(webhook.object_attributes.id)

filter: webhook.object_attributes.status in ["failed", "canceled"]

Available GitLab webhook headers​

HeaderDescriptionExample
X-Gitlab-EventEvent typePipeline Hook, Deployment Hook, Release Hook
X-Gitlab-TokenSecret token, sent as plain text (if configured)(if configured)
X-Gitlab-InstanceGitLab instance URLhttps://gitlab.com
webhook-signatureHMAC-SHA256 signature (if a signing token is configured)v1,<base64_signature>
webhook-idUnique message ID used in signature computationmsg_2wF...
webhook-timestampUnix timestamp used in signature computation1717000000

Next steps​

Further reading​

GitLab Official Documentation​

  • Webhooks - Complete guide to GitLab webhook configuration and setup
  • Webhook Events - Event-specific payload structures (pipeline, deployment, release)
  • Pipeline Events - Pipeline webhook payload structure and build details
  • Deployment Events - Deployment webhook payload and environment information