Implementation:OpenHands OpenHands Webhook Installation Utils

Knowledge Sources	OpenHands
Domains	Platform_Integration, GitLab_API, Webhook_Management
Last Updated	2026-02-11 21:00 GMT

Overview

Concrete tool for verifying preconditions and installing GitLab webhooks on projects or groups, provided by the OpenHands enterprise GitLab integration layer.

Description

The webhook_installation module provides two primary functions and associated constants for managing the GitLab webhook lifecycle.

The verify_webhook_conditions function performs pre-flight validation before attempting webhook installation. It checks that the target resource (project or group) exists, that the authenticated user has sufficient permissions to create webhooks, and that no duplicate webhook with the same URL already exists on the resource. This prevents redundant webhook registrations and surfaces permission errors early.

The install_webhook_on_resource function performs the actual webhook creation on the target GitLab resource. It constructs the webhook configuration using the WEBHOOK_NAME constant (set to 'OpenHands Resolver') and the configured callback URL, registers the webhook with the appropriate event triggers (merge request events, issue events, note events), and returns the created webhook details for confirmation.

The module defines two key constants: WEBHOOK_NAME which is the display name 'OpenHands Resolver' used when registering the webhook, and SCOPES which is a list of GitLab event scopes that the webhook subscribes to (such as merge request hooks, issue hooks, and note hooks).

Usage

Use verify_webhook_conditions before calling install_webhook_on_resource to ensure all preconditions are met. This two-step pattern allows callers to surface validation errors to users before making any state changes on the GitLab side. The functions are typically invoked during organization onboarding or when a user enables the GitLab integration for a repository.

Code Reference

Source Location

• Repository: OpenHands
• File: enterprise/integrations/gitlab/webhook_installation.py
• Lines: 1-196

Signature

WEBHOOK_NAME: str = 'OpenHands Resolver'
SCOPES: list[str] = [...]

async def verify_webhook_conditions(
    gitlab_client,
    resource_type: str,
    resource_id: int,
    webhook_url: str,
) -> dict:
    ...

async def install_webhook_on_resource(
    gitlab_client,
    resource_type: str,
    resource_id: int,
    webhook_url: str,
    secret_token: str,
) -> dict:
    ...

Import

from enterprise.integrations.gitlab.webhook_installation import (
    verify_webhook_conditions,
    install_webhook_on_resource,
)

I/O Contract

Inputs

Name	Type	Required	Description
gitlab_client	GitLab client	Yes	Authenticated GitLab API client instance
resource_type	str	Yes	The type of GitLab resource to install the webhook on ("project" or "group")
resource_id	int	Yes	The numeric ID of the target GitLab project or group
webhook_url	str	Yes	The callback URL that GitLab will POST webhook events to
secret_token	str	Yes	A shared secret used to verify the authenticity of incoming webhook payloads (for install_webhook_on_resource only)

Outputs

verify_webhook_conditions:

Name	Type	Description
result	dict	Validation result containing success boolean and error message if validation failed, or resource metadata if successful

install_webhook_on_resource:

Name	Type	Description
webhook	dict	The created webhook details including webhook ID, URL, and subscribed event scopes

Constants

Constant	Value	Description
WEBHOOK_NAME	'OpenHands Resolver'	Display name registered with the GitLab webhook
SCOPES	list[str]	List of GitLab event types the webhook subscribes to (merge request events, issue events, note events, etc.)

Usage Examples

from enterprise.integrations.gitlab.webhook_installation import (
    verify_webhook_conditions,
    install_webhook_on_resource,
)

# Step 1: Verify preconditions
validation = await verify_webhook_conditions(
    gitlab_client=gl_client,
    resource_type="project",
    resource_id=12345,
    webhook_url="https://app.openhands.ai/webhooks/gitlab",
)

if not validation.get("success"):
    raise ValueError(f"Webhook precondition failed: {validation.get('error')}")

# Step 2: Install the webhook
webhook = await install_webhook_on_resource(
    gitlab_client=gl_client,
    resource_type="project",
    resource_id=12345,
    webhook_url="https://app.openhands.ai/webhooks/gitlab",
    secret_token="whsec_abc123secret",
)

print(f"Webhook installed with ID: {webhook['id']}")

Related Pages

Environment

• Environment:OpenHands_OpenHands_Integration_Credentials