Webhooks

Receive SCM events to trigger automations

Webhooks are standalone endpoints that receive events from your Git provider (GitHub or GitLab). Once created, a webhook can be shared across multiple automations — you configure the connection to your SCM once and reuse it wherever you need pull request triggers.

Webhooks are available on the Enterprise plan only. See Plans and limits.

How webhooks work

1. You create a webhook in Ona, choosing a provider (GitHub or GitLab) and a scope (repository or organization). The scope can be configured later, but the webhook won’t process events until one is set.
2. Ona generates a payload URL and a secret token.
3. You register the payload URL and secret in your Git provider’s webhook settings.
4. When PR events occur, the Git provider sends a signed payload to Ona.
5. Ona verifies the signature, matches the event to bound automations, and triggers them.

A single webhook can be bound to multiple automations.

Scope types

Type	Description
Repository	Scoped to one or more specific repositories. Events from other repositories are ignored.
Organization	Scoped to an entire SCM organization or group. Events from any repository in that organization are accepted.

Repository-scoped webhooks support up to 100 repositories per webhook.

Creating a webhook

Dashboard

1. Go to Automations and click Webhooks in the top bar.

2. Click + Webhook to open the creation dialog.
3. Select the provider (GitHub or GitLab).
4. Choose the type (Organization or Repository).
5. Enter a name for the webhook.
6. Click Create Webhook.

After creation, Ona shows the payload URL and secret token. You can also select the scope — the specific repositories or organization this webhook should accept events from.

You can skip the scope configuration during creation and set it later from the webhook details panel. The webhook will show a “Setup incomplete” badge until a scope is configured.

CLI

gitpod webhook create \
  --name "My Webhook" \
  --type repository \
  --scope "owner/repo" \
  --provider github

The CLI returns the webhook ID and payload URL but not the secret. To retrieve the secret token, run:

gitpod webhook secret get <webhook-id>

Once you have both values, register them in your Git provider as described in the next section.

Registering the webhook in your Git provider

After creating the webhook in Ona, register it in your Git provider so events are delivered.

GitHub

Repository webhook

1. Go to https://github.com/<owner>/<repo>/settings/hooks and click Add webhook.
2. Enter the Payload URL from Ona.
3. Enter the Secret from Ona.
4. Set Content type to application/json.
5. Select Let me select individual events and check Pull requests.
6. Click Add webhook.

Organization webhook

1. Go to https://github.com/organizations/<org>/settings/hooks and click Add webhook.
2. Enter the Payload URL from Ona.
3. Enter the Secret from Ona.
4. Set Content type to application/json.
5. Select Let me select individual events and check Pull requests.
6. Click Add webhook.

GitHub webhook documentation

GitLab

Project webhook

1. Go to https://gitlab.com/<owner>/<project>/-/hooks and click Add new webhook.
2. Enter the URL (payload URL from Ona).
3. Enter the Secret token from Ona.
4. Check Merge request events.
5. Click Add webhook.

Group webhook

1. Go to https://gitlab.com/groups/<group>/-/hooks and click Add new webhook.
2. Enter the URL (payload URL from Ona).
3. Enter the Secret token from Ona.
4. Check Merge request events.
5. Click Add webhook.

GitLab webhook documentation

Managing webhooks

Viewing webhook details

Click any webhook in the list to open its details panel. The panel shows:

• Webhook name
• Payload URL and secret token (copyable)
• Provider and scope configuration

Updating scope

You can change the repositories or organization a webhook is scoped to at any time from the details panel. The provider and type cannot be changed after creation — create a new webhook instead.

Rotating the secret

If a webhook secret is compromised, rotate it from the details panel. After rotation:

1. Copy the new secret from Ona.
2. Update the secret in your Git provider’s webhook settings.

The old secret is immediately invalidated.

Deleting a webhook

When you delete a webhook:

• Any automations bound to it have their pull request triggers converted to manual triggers. They stop receiving PR events but can still be run manually.
• Running executions continue until they complete.
• The webhook is removed from Ona but not from your Git provider. Remove it from your provider’s settings separately to stop sending events.

Binding webhooks to automations

When configuring a pull request trigger on an automation, select a webhook from the dropdown. You can also create a new webhook inline from the trigger configuration.

Multiple automations can share the same webhook. Each automation independently defines which PR events it responds to (opened, updated, merged, etc.).

Security

Webhooks authenticate using HMAC signature verification. When your Git provider sends an event, it signs the payload using the shared secret. Ona verifies the signature before processing the event. Events with invalid signatures are rejected.

Keep your webhook secret secure. If compromised, rotate it immediately.

Next steps

• Pull request triggers — configure which PR events trigger your automations
• Creating automations — set up automations that use webhooks
• Plans and limits — webhook availability by plan