Update Webhook

Unary · Webhooks Updates a webhook’s configuration. Use this method to:

Change webhook name or description
Change webhook scopes (the target repositories or organization)

Note: The webhook type and provider cannot be changed after creation.

Examples

Update webhook name: Changes the webhook’s display name.

webhookId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
name: "Updated Webhook Name"

Update webhook scopes: Changes the webhook’s target repositories.

webhookId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
scopes:
  - host: "github.com"
    owner: "gitpod-io"
    name: "new-repo"

Endpoint

POST /api/gitpod.v1.WebhookService/UpdateWebhook

Send a Bearer token as described in Authentication. If your organization uses a custom management-plane domain, replace https://app.ona.com with that domain.

Request example

export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.WebhookService/UpdateWebhook" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "webhookId": "<webhook-id>"
}'

import gitpod.v1.webhook_pb2 as webhook_pb2
from ona_sdk import create_client_from_env

ona = create_client_from_env()
request = webhook_pb2.UpdateWebhookRequest(
    webhook_id="<webhook-id>",
)
response = ona.services.webhook.update_webhook(request)
print(response)

import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { UpdateWebhookRequestSchema } from "@gitpod/sdk/gitpod/v1/webhook_pb";

async function main() {
  const ona = createClientFromEnv();
  const request = create(UpdateWebhookRequestSchema, {
    webhookId: "<webhook-id>",
  });
  const response = await ona.services.webhook.updateWebhook(request);
  console.log(response);
}

main().catch(console.error);

package main

import (
	"context"
	"fmt"
	"log"

	"connectrpc.com/connect"
	"github.com/gitpod-io/gitpod-sdk-go/sdk"
	gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)

func main() {
	ona, err := sdk.NewFromEnv()
	if err != nil {
		log.Fatal(err)
	}

	request := connect.NewRequest(&gitpodpb.UpdateWebhookRequest{
		WebhookId: "<webhook-id>",
	})
	response, err := ona.Services.Webhook.UpdateWebhook(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "webhookId": "<webhook-id>"
}

Request

gitpod.v1.UpdateWebhookRequest UpdateWebhookRequest updates a webhook’s configuration.

Field	Type	Required	Description
`webhookId`	string	No	Constraints: `string.uuid=true`.
`name`	string	No	name is the display name of the webhook Constraints: `string.max_len=80, string.min_len=1`.
`description`	string	No	description is an optional description of the webhook’s purpose Constraints: `string.max_len=500`.
`scope`	string	No	Deprecated. Deprecated: Use scopes instead. scope is the target of the webhook: - For REPOSITORY type: “owner/repo” (e.g., “gitpod-io/gitpod”) - For ORGANIZATION type: “owner” (e.g., “gitpod-io”) Note: The webhook type and provider cannot be changed after creation. Constraints: `string.max_len=255`.
`scopes`	array of WebhookRepositoryScope	No	scopes replaces the webhook’s repository scopes. For REPOSITORY type: each entry represents a specific repository with full SCM data. When provided, takes precedence over the deprecated scope field. Note: The webhook type and provider cannot be changed after creation. Constraints: `repeated.max_items=100`.
`organizationScope`	WebhookOrganizationScope	No	organization_scope replaces the webhook’s organization scope. For ORGANIZATION type: identifies the organization and its SCM host. When provided, takes precedence over the deprecated scope field. Note: The webhook type and provider cannot be changed after creation.

Response

gitpod.v1.UpdateWebhookResponse

Field	Type	Required	Description
`webhook`	Webhook	No

Webhook

Webhook represents a webhook endpoint for receiving SCM events.gitpod.v1.Webhook

Field	Type	Required	Description
`id`	string	No	id is the unique identifier of the webhook Constraints: `string.uuid=true`.
`metadata`	Metadata	No	metadata contains organizational and ownership information
`spec`	Spec	No	spec contains the webhook configuration
`url`	string	No	url is the generated webhook endpoint URL Format: https://{domain}/webhooks/{id} Read-only, computed from id
`boundWorkflowCount`	integer	No	bound_workflow_count is the number of workflows bound to this webhook Read-only, computed from workflow_webhook_bindings
`lastTriggeredAt`	RFC 3339 timestamp	No	last_triggered_at is when the webhook was last triggered by an incoming event Read-only, updated automatically when the webhook receives an event

Metadata

Metadata contains organizational and ownership information.gitpod.v1.Webhook.Metadata

Field	Type	Required	Description
`organizationId`	string	No	organization_id is the ID of the organization that owns this webhook Constraints: `string.uuid=true`.
`name`	string	No	name is the display name of the webhook
`description`	string	No	description is an optional description of the webhook’s purpose
`creator`	Subject	No	creator is the identity of who created the webhook
`createdAt`	RFC 3339 timestamp	No	created_at is when the webhook was created
`updatedAt`	RFC 3339 timestamp	No	updated_at is when the webhook was last updated

Spec

Spec contains the webhook configuration.gitpod.v1.Webhook.Spec

Field	Type	Required	Description
`type`	WebhookType	No	type determines the scope level of the webhook Constraints: `enum.defined_only=true`.
`scope`	string	No	Deprecated. Deprecated: Use scopes instead. Kept for backward compatibility. scope is the target of the webhook: - For REPOSITORY type: “owner/repo” (e.g., “gitpod-io/gitpod”) - For ORGANIZATION type: “owner” (e.g., “gitpod-io”)
`provider`	WebhookProvider	No	provider is the Git provider (github, gitlab) Constraints: `enum.defined_only=true`.
`scopes`	array of WebhookRepositoryScope	No	scopes is the list of repository scopes for this webhook. For REPOSITORY type: each entry represents a specific repository. When scopes is non-empty, it takes precedence over the deprecated scope field. Constraints: `repeated.max_items=100`.
`organizationScope`	WebhookOrganizationScope	No	organization_scope is the SCM organization scope for this webhook. For ORGANIZATION type: identifies the organization and its SCM host. When set, takes precedence over the deprecated scope field.

WebhookOrganizationScope

WebhookOrganizationScope represents an SCM organization in the webhook’s scope.gitpod.v1.WebhookOrganizationScope

Field	Type	Required	Description
`host`	string	No	host is the SCM host (e.g., “github.com”, “gitlab.com”) Constraints: `string.min_len=1`.
`name`	string	No	name is the organization or group name (e.g., “gitpod-io”) Constraints: `string.min_len=1`.

WebhookRepositoryScope

WebhookRepositoryScope represents a repository in the webhook’s scope. Contains SCM repository information needed to generate execution contexts. The clone URL can be derived as https://{host}/{owner}/{name}.gitgitpod.v1.WebhookRepositoryScope

Field	Type	Required	Description
`host`	string	No	host is the SCM host (e.g., “github.com”, “gitlab.com”) Constraints: `string.min_len=1`.
`owner`	string	No	owner is the repository owner or organization (e.g., “gitpod-io”) Constraints: `string.min_len=1`.
`name`	string	No	name is the repository name (e.g., “gitpod”) Constraints: `string.min_len=1`.

WebhookProvider

WebhookProvider identifies the Git provider.

Value	Number	Description
`WEBHOOK_PROVIDER_UNSPECIFIED`	0
`WEBHOOK_PROVIDER_GITHUB`	1
`WEBHOOK_PROVIDER_GITLAB`	2
`WEBHOOK_PROVIDER_BITBUCKET`	3	WEBHOOK_PROVIDER_BITBUCKET is the bitbucket cloud provider.

WebhookType

WebhookType determines the scope level of the webhook.

Value	Number	Description
`WEBHOOK_TYPE_UNSPECIFIED`	0
`WEBHOOK_TYPE_SCM_REPOSITORY`	1	Scoped to a specific repository (e.g., “owner/repo”)
`WEBHOOK_TYPE_SCM_ORGANIZATION`	2	Scoped to an organization (e.g., “owner” - all repos)

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Examples

Endpoint

Request example

Request

Response

​Examples

​Endpoint

​Request example

​Request

​Response

​Related types

Examples

Endpoint

Request example

Request

Response

Related types