Create Webhook

Unary · Webhooks Creates a new webhook for receiving SCM events. Use this method to:

Set up webhooks for repository or organization events
Configure webhook scopes and provider

Examples

Create repository webhook with multiple scopes: Creates a webhook scoped to specific repositories.

name: "My Repo Webhook"
type: WEBHOOK_TYPE_SCM_REPOSITORY
scopes:
  - host: "github.com"
    owner: "gitpod-io"
    name: "gitpod"
  - host: "github.com"
    owner: "gitpod-io"
    name: "gitpod-next"
provider: WEBHOOK_PROVIDER_GITHUB

Create organization webhook: Creates a webhook scoped to all repositories in an organization.

name: "Org Webhook"
type: WEBHOOK_TYPE_SCM_ORGANIZATION
organizationScope:
  host: "github.com"
  name: "gitpod-io"
provider: WEBHOOK_PROVIDER_GITHUB

Endpoint

POST /api/gitpod.v1.WebhookService/CreateWebhook

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/CreateWebhook" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "<name>"
}'

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

ona = create_client_from_env()
request = webhook_pb2.CreateWebhookRequest(
    name="<name>",
)
response = ona.services.webhook.create_webhook(request)
print(response)

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

async function main() {
  const ona = createClientFromEnv();
  const request = create(CreateWebhookRequestSchema, {
    name: "<name>",
  });
  const response = await ona.services.webhook.createWebhook(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.CreateWebhookRequest{
		Name: "<name>",
	})
	response, err := ona.Services.Webhook.CreateWebhook(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "name": "<name>"
}

Request

gitpod.v1.CreateWebhookRequest CreateWebhookRequest creates a new webhook.

Field	Type	Required	Description
`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`.
`type`	WebhookType	No	type determines the scope level of the webhook Constraints: `enum.defined_only=true, enum.not_in=0`.
`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”) - Empty string is allowed for webhooks that don’t require scope filtering Constraints: `string.max_len=255`.
`provider`	WebhookProvider	No	provider is the Git provider Constraints: `enum.defined_only=true, enum.not_in=0`.
`scopes`	array of WebhookRepositoryScope	No	scopes is the list of repository scopes for this webhook. For REPOSITORY type: each entry represents a specific repository with full SCM data. When provided, 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 provided, takes precedence over the deprecated scope field.

Response

gitpod.v1.CreateWebhookResponse

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