> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Webhook
> Creates a new webhook for receiving SCM events.
`Unary` ยท [`Webhooks`](/docs/api-reference/generated/webhook/overview)
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.
```yaml theme={null}
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.
```yaml theme={null}
name: "Org Webhook"
type: WEBHOOK_TYPE_SCM_ORGANIZATION
organizationScope:
host: "github.com"
name: "gitpod-io"
provider: WEBHOOK_PROVIDER_GITHUB
```
## Endpoint
```text theme={null}
POST /api/gitpod.v1.WebhookService/CreateWebhook
```
Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.
## Request example
```bash cURL theme={null}
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.WebhookService/CreateWebhook" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": ""
}'
```
```python Python theme={null}
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="",
)
response = ona.services.webhook.create_webhook(request)
print(response)
```
```typescript TypeScript theme={null}
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: "",
});
const response = await ona.services.webhook.createWebhook(request);
console.log(response);
}
main().catch(console.error);
```
```go Go theme={null}
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: "",
})
response, err := ona.Services.Webhook.CreateWebhook(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"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](#enum-gitpod-v1-webhook-type) | 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](#enum-gitpod-v1-webhook-provider) | No | provider is the Git provider Constraints: `enum.defined_only=true, enum.not_in=0`. |
| `scopes` | array of [WebhookRepositoryScope](#type-gitpod-v1-webhook-repository-scope) | 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](#type-gitpod-v1-webhook-organization-scope) | 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](#type-gitpod-v1-webhook) | No | |
## Related types
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](#type-gitpod-v1-webhook-metadata) | No | metadata contains organizational and ownership information |
| `spec` | [Spec](#type-gitpod-v1-webhook-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 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 contains the webhook configuration.
`gitpod.v1.Webhook.Spec`
| Field | Type | Required | Description |
| ------------------- | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | [WebhookType](#enum-gitpod-v1-webhook-type) | 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](#enum-gitpod-v1-webhook-provider) | 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 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 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}.git
`gitpod.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 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 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) |