---
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`

Creates a new webhook on the specified repository.

Example:

```
$ curl -X POST -u credentials -H 'Content-Type: application/json'
  https://api.bitbucket.org/2.0/repositories/my-workspace/my-repo-slug/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.

Note that 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`.

Also note that the `url` must properly resolve and cannot be an
internal, non-routed address.

## 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 repository.
- `404` — If the repository does not exist.

---

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