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

# Update a webhook for a repository

`PUT /repositories/{workspace}/{repo_slug}/hooks/{uid}`

## Request

- Base URL: `https://api.bitbucket.org/2.0`
- URL: `https://api.bitbucket.org/2.0/repositories/{workspace}/{repo_slug}/hooks/{uid}`
- 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`

Updates the specified webhook subscription.

The following properties can be mutated:

* `description`
* `url`
* `secret`
* `active`
* `events`

The hook's secret is used as a key to generate the HMAC hex digest
sent in the `X-Hub-Signature` header at delivery time. This
signature is only generated when the hook has a secret.

Set the hook's secret by passing the new value in the `secret`
field. Passing a `null` value in the `secret` field will remove
the secret from the hook. The hook's secret can be left unchanged
by not passing the `secret` field in the request.

## Path parameters

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

## Response `200`

The webhook subscription object.

- 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 update the webhook.
- `404`: If the webhook or repository does not exist.

## Changes

- **2026-10-03** `869214428f35`: 3 breaking, 6 info
  - added the new path request parameter `repo_slug`
  - added the new path request parameter `uid`
  - added the new path request parameter `workspace`
  - api operation id `update_repository_hook` was added
  - …5 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 `200`
  - added the new `pullrequest:push` enum value to the `allOf[subschema #2: Webhook Subscription]/events/items/` response property for the response status `200`

[Operation history](https://skmtc.dev/atlassian/apis/bitbucket-api/changes/repositories/:workspace/:repo_slug/hooks/:uid/put.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)