---
title: "Create a webhook for a repository"
method: POST
path: "/repositories/{workspace}/{repo_slug}/hooks"
tags: ["Repositories", "Webhooks"]
---

# Create a webhook for a repository

`POST /repositories/{workspace}/{repo_slug}/hooks`

## Request

- Base URL: `https://api.bitbucket.org/2.0`
- URL: `https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/hooks`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://bitbucket.org/site/oauth2/authorize`
    - Token URL: `https://bitbucket.org/site/oauth2/access_token` scopes: `webhook`
  - HTTP basic
  - API key in header `Authorization`

Creates a new webhook on the specified repository.

Workspace webhooks are fired for events from all repositories
contained by that workspace.

Example:
```
$ curl -X POST -u credentials -H 'Content-Type: application/json'
  https://api.bitbucket.org/2.0/workspaces/my-workspace/hooks
  -d '
    {
      "description": "Webhook Description",
      "url": "https://example.com/",
      "active": true,
      "secret": "this is a really bad secret",
      "events": [
        "repo:push",
        "issue:created",
        "issue:updated"
      ]
    }'
```

When the `secret` is provided it will be used as the key to
generate a HMAC digest value sent in the `X-Hub-Signature` header
at delivery time. Passing a `null` or empty `secret` or not
passing a `secret` will leave the webhook's secret unset.
Bitbucket only generates the `X-Hub-Signature` when the webhook's
secret is set.

This call requires the webhook scope, as well as any scope
that applies to the events that the webhook subscribes to. In the
example above that means: `webhook`, `repository` and `issue`.

The `url` must properly resolve and cannot be an internal,
non-routed address.

## Path parameters

- `workspace` string, required
- `repo_slug` string, required

## Response `201`

If the webhook was registered successfully.

- WebhookSubscription: A Webhook subscription.
  - `type` string, required
  - `uuid` string: The webhook's id.
  - `url` string, uri: The URL events get delivered to.
  - `description` string: A user-defined description of the webhook.
  - `subject_type` 'repository' | 'workspace': The type of entity. Set to either `repository` or `workspace` based on where the subscription is defined.
  - `subject` Object: Base type for most resource objects. It defines the common `type` element that identifies an object's type. It also identifies the element as Swagger's `discriminator`.
    - `type` string, required
  - `active` boolean: Whether or not the webhook subscription is enabled.
  - `created_at` string, date-time: The timestamp when the webhook subscription was created.
  - `events` string[]: The events this webhook is subscribed to.
  - `secret_set` boolean: Indicates whether or not the hook has an associated secret. It is not possible to see the hook's secret. This field is ignored during updates.
  - `secret` string: The secret to associate with the hook. The secret is never returned via the API. As such, this field is only used during updates. The secret can be set to `null`` or `""`` to remove the secret (or create a hook with no secret). Leaving out the secret field during updates will leave the secret unchanged. Leaving out the secret during creation will create a hook with no secret.
  - `links` WebhooksSubscriptionLinks: A link to a resource related to this object.
    - `self` WebhooksSubscriptionLink
      - `href` string, uri

## Other responses

- `403`: If the authenticated user does not have permission to install webhooks on the specified repository.
- `404`: If the webhook or repository does not exist.

## Changes

- **2026-10-03** `869214428f35`: 2 breaking, 6 info
  - added the new path request parameter `repo_slug`
  - added the new path request parameter `workspace`
  - api operation id `create_repository_hook` was added
  - added the optional property `allOf[subschema #2: Webhook Subscription]/links` to the response with the `201` status
  - …4 more
- **2026-07-13** `d344164ecb11`: 2 warning
  - added the new `pipeline:span_created` enum value to the `allOf[subschema #2: Webhook Subscription]/events/items/` response property for the response status `201`
  - added the new `pullrequest:push` enum value to the `allOf[subschema #2: Webhook Subscription]/events/items/` response property for the response status `201`

[Operation history](https://skmtc.dev/atlassian/apis/bitbucket-api/changes/repositories/:workspace/:repo_slug/hooks/post.md)

---

[API](https://skmtc.dev/atlassian/apis/bitbucket-api.md) - [All operations](https://skmtc.dev/atlassian/apis/bitbucket-api/llms.txt) - [OpenAPI document](https://skmtc.dev/atlassian/apis/bitbucket-api/revisions/6ae783fa75da?raw)