---
title: "Create a webhook for a workspace"
method: POST
path: "/workspaces/{workspace}/hooks"
tags: ["Workspaces", "Webhooks"]
---

# Create a webhook for a workspace

`POST /workspaces/{workspace}/hooks`

Creates a new webhook on the specified workspace.

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.

Only workspace owners can install webhooks on workspaces.

## 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
  - `created_at` string, date-time
  - `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.

## Other responses

- `403` — If the authenticated user does not have permission to install webhooks on the specified workspace.
- `404` — If the specified workspace does not exist.

---

[API](https://skmtc.net/bitbucket/apis/bitbucket-api.md) · [All operations](https://skmtc.net/bitbucket/apis/bitbucket-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bitbucket/bitbucket-api/versions/7e9be973015d/schema)