> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab Webhook Setup Guide

> Configure GitLab to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](https://docs.stackone.com/connectors/gitlab.md#getting-started) on the GitLab connector page.

## Connect GitLab webhooks

GitLab sends events to StackOne through a webhook added in each project. Paste the StackOne Native Webhook URL into a new project webhook and select the triggers you want to receive.

**1. Retrieve StackOne Native Webhook URL**

The **Native Webhook URL** is generated once an account has been linked.

<ul>
  <li>Open the linked account in StackOne.</li>
  <li>Copy the value from **Native Webhook URL**.</li>
</ul>

**2. Open the project webhook settings**

Sign in to your [GitLab account](https://gitlab.com/users/sign_in) and open the project you want to receive events from.

<ul>
  <li>In the left sidebar, select **Settings** > **Webhooks**.</li>
</ul>

![The GitLab project sidebar with Settings expanded and Webhooks highlighted](https://mintcdn.com/stackone-60/7ZQSeSQo1RxZCE9Q/connectors/gitlab/images/events-open-webhooks.png?fit=max\&auto=format\&n=7ZQSeSQo1RxZCE9Q\&q=85\&s=70eea34abd282ccb9201d1a7c3ebc44c)

**3. Add a new webhook**

On the **Webhooks** page, click **Add new webhook**.

![The GitLab Webhooks page with the Add new webhook button highlighted](https://mintcdn.com/stackone-60/7ZQSeSQo1RxZCE9Q/connectors/gitlab/images/events-add-new-webhook.png?fit=max\&auto=format\&n=7ZQSeSQo1RxZCE9Q\&q=85\&s=191a2abc5463ec54d75fd3e6087faf15)

**4. Paste the Native Webhook URL**

Fill in the webhook details.

<ul>
  <li>**Name (optional)**: enter a name such as `StackOne`.</li>
  <li>**URL**: paste the StackOne Native Webhook URL.</li>
  <li>Leave **Signing token** and **Secret token (not recommended)** empty. StackOne does not verify them.</li>
</ul>

![The Add new webhook form with the Name and URL fields highlighted](https://mintcdn.com/stackone-60/7ZQSeSQo1RxZCE9Q/connectors/gitlab/images/events-webhook-url.png?fit=max\&auto=format\&n=7ZQSeSQo1RxZCE9Q\&q=85\&s=9d5bd0d8576a66046c3304a2d98c3b78)

**5. Select the triggers**

Under **Trigger**, tick the events you want StackOne to receive. See **Available webhook events** below for the events each trigger sends.

<ul>
  <li>For **Push events**, keep **All branches** selected to receive pushes to every branch.</li>
</ul>

![The Trigger checkboxes of the Add new webhook form, all ticked](https://mintcdn.com/stackone-60/7ZQSeSQo1RxZCE9Q/connectors/gitlab/images/events-select-triggers.png?fit=max\&auto=format\&n=7ZQSeSQo1RxZCE9Q\&q=85\&s=f133e2416a0779a2b247b49b082e2bce)

**6. Save the webhook**

Keep **Enable SSL verification** ticked and click **Add webhook**.

![The bottom of the webhook form with the Add webhook button highlighted](https://mintcdn.com/stackone-60/7ZQSeSQo1RxZCE9Q/connectors/gitlab/images/events-add-webhook.png?fit=max\&auto=format\&n=7ZQSeSQo1RxZCE9Q\&q=85\&s=ce6ef813cf975afbef6aafcafedc61f8)

**7. Test the webhook**

GitLab shows **Webhook created** and lists the new webhook. Use the **Test** menu on the webhook to send a sample event for a trigger and confirm that it reaches StackOne.

![The GitLab webhook list showing the new StackOne webhook with the Test menu highlighted](https://mintcdn.com/stackone-60/7ZQSeSQo1RxZCE9Q/connectors/gitlab/images/events-test-webhook.png?fit=max\&auto=format\&n=7ZQSeSQo1RxZCE9Q\&q=85\&s=ffa00697892ae5432d5da50ecc0ba95a)

## Available webhook events

The following GitLab events are supported. GitLab only sends the events whose trigger is ticked on the webhook, and StackOne only delivers the events you enable in StackOne.

**1. Code events**

Events for pushes and tags. Enable **Push events** and **Tag push events**.

<ul>
  <li>**Push** (`push`) — Fired when commits are pushed to a branch of a project</li>
  <li>**Tag Push** (`tag_push`) — Fired when a tag is created or deleted in a project</li>
</ul>

**2. Work item and issue events**

Events for issues and other work items. Enable **Work item events** (and **Confidential work items events** for confidential ones).

<ul>
  <li>**Issue Opened** (`issue.open`) — Fired when an issue is opened in a project</li>
  <li>**Issue Closed** (`issue.close`) — Fired when an issue is closed in a project</li>
  <li>**Issue Reopened** (`issue.reopen`) — Fired when an issue is reopened in a project</li>
  <li>**Issue Updated** (`issue.update`) — Fired when an issue is edited in a project</li>
  <li>**Work Item Opened** (`work_item.open`) — Fired when a work item such as a task or epic is opened</li>
  <li>**Work Item Closed** (`work_item.close`) — Fired when a work item such as a task or epic is closed</li>
  <li>**Work Item Reopened** (`work_item.reopen`) — Fired when a work item such as a task or epic is reopened</li>
  <li>**Work Item Updated** (`work_item.update`) — Fired when a work item such as a task or epic is edited</li>
</ul>

**3. Merge request events**

Events for the merge request lifecycle and approvals. Enable **Merge request events**.

<ul>
  <li>**Merge Request Opened** (`merge_request.open`) — Fired when a merge request is opened</li>
  <li>**Merge Request Closed** (`merge_request.close`) — Fired when a merge request is closed without merging</li>
  <li>**Merge Request Reopened** (`merge_request.reopen`) — Fired when a merge request is reopened</li>
  <li>**Merge Request Updated** (`merge_request.update`) — Fired when a merge request is updated</li>
  <li>**Merge Request Merged** (`merge_request.merge`) — Fired when a merge request is merged</li>
  <li>**Merge Request Approval Added** (`merge_request.approval`) — Fired when a merge request is approved by one approver</li>
  <li>**Merge Request Approved** (`merge_request.approved`) — Fired when a merge request is fully approved</li>
  <li>**Merge Request Approval Removed** (`merge_request.unapproval`) — Fired when a merge request is unapproved by one approver</li>
  <li>**Merge Request Unapproved** (`merge_request.unapproved`) — Fired when a merge request is no longer fully approved</li>
</ul>

**4. Comment and reaction events**

Events for comments and emoji reactions. Enable **Comments**, **Confidential comments** and **Emoji events**.

<ul>
  <li>**Comment Created** (`note.create`) — Fired when a comment is created on a commit, merge request, issue or snippet</li>
  <li>**Comment Updated** (`note.update`) — Fired when a comment is updated on a commit, merge request, issue or snippet</li>
  <li>**Emoji Reaction Awarded** (`emoji.award`) — Fired when an emoji reaction is added to an issue, merge request, snippet or comment</li>
  <li>**Emoji Reaction Revoked** (`emoji.revoke`) — Fired when an emoji reaction is removed from an issue, merge request, snippet or comment</li>
</ul>

**5. CI/CD and deployment events**

Events for pipelines, jobs, deployments and feature flags. Enable **Pipeline events**, **Job events**, **Deployment events** and **Feature flag events**.

<ul>
  <li>**Pipeline Status Changed** (`pipeline`) — Fired when a pipeline is created or its status changes</li>
  <li>**Job Status Changed** (`build`) — Fired when a CI/CD job is created or its status changes</li>
  <li>**Deployment Status Changed** (`deployment`) — Fired when a deployment starts, succeeds, fails, is canceled or is approved or rejected</li>
  <li>**Feature Flag Toggled** (`feature_flag`) — Fired when a feature flag is turned on or off</li>
</ul>

**6. Release, milestone and wiki events**

Events for releases, milestones and wiki pages. Enable **Releases events**, **Milestone events** and **Wiki page events**.

<ul>
  <li>**Release Created** (`release.create`) — Fired when a release is created in a project</li>
  <li>**Release Updated** (`release.update`) — Fired when a release is updated in a project</li>
  <li>**Release Deleted** (`release.delete`) — Fired when a release is deleted in a project</li>
  <li>**Milestone Created** (`milestone.create`) — Fired when a project milestone is created</li>
  <li>**Milestone Closed** (`milestone.close`) — Fired when a project milestone is closed</li>
  <li>**Milestone Reopened** (`milestone.reopen`) — Fired when a project milestone is reopened</li>
  <li>**Milestone Deleted** (`milestone.delete`) — Fired when a project milestone is deleted</li>
  <li>**Wiki Page Created** (`wiki_page.create`) — Fired when a project wiki page is created</li>
  <li>**Wiki Page Updated** (`wiki_page.update`) — Fired when a project wiki page is updated</li>
  <li>**Wiki Page Deleted** (`wiki_page.delete`) — Fired when a project wiki page is deleted</li>
</ul>

**7. Security events**

Events for expiring access tokens and vulnerabilities. Enable **Resource access token events** and **Vulnerability events** (Ultimate only).

<ul>
  <li>**Access Token Expiring** (`access_token.expiring_access_token`) — Fired when a project or group access token is about to expire</li>
  <li>**Vulnerability Created or Updated** (`vulnerability`) — Fired when a vulnerability is created or its state or details change</li>
</ul>

**8. Group-only events**

Sent only by group webhooks (GitLab Premium or Ultimate), on the group's **Settings** > **Webhooks** page.

<ul>
  <li>**Group Member Added** (`user_add_to_group`) — Fired when a user is added to the group</li>
  <li>**Group Member Updated** (`user_update_for_group`) — Fired when a group member access level or expiry changes</li>
  <li>**Group Member Removed** (`user_remove_from_group`) — Fired when a user is removed from the group</li>
  <li>**Group Access Requested** (`user_access_request_to_group`) — Fired when a user requests access to the group</li>
  <li>**Group Access Request Denied** (`user_access_request_denied_for_group`) — Fired when a group access request is denied</li>
  <li>**Group Project Created** (`project_create`) — Fired when a project is created in the group</li>
  <li>**Group Project Deleted** (`project_destroy`) — Fired when a project is deleted in the group</li>
  <li>**Subgroup Created** (`subgroup_create`) — Fired when a subgroup is created in the group</li>
  <li>**Subgroup Deleted** (`subgroup_destroy`) — Fired when a subgroup is deleted in the group</li>
</ul>

## Delivery format

Details of how GitLab delivers events to StackOne.

**1. One event per request**

Each request carries a single JSON event. GitLab retries a delivery that times out, so the same event can arrive more than once. Each event carries the ID of the affected record (for example the issue IID or the pipeline ID).

**2. Failing deliveries disable the webhook**

GitLab marks a webhook as temporarily disabled after 4 consecutive failed deliveries and disables it after 40. StackOne answers every delivery with 200, including event types it does not handle, so the webhook stays enabled.

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.