The Bitbucket Cloud REST API

Webhooks

Webhooks provide a way to configure Bitbucket Cloud to make requests to your server (or another external service) whenever certain events occur in Bitbucket Cloud.

A webhook consists of:

A subject -- The resource that generates the events. Currently, this resource is the repository, user account, or team where you create the webhook.
One or more event -- The default event is a repository push, but you can select multiple events that can trigger the webhook.
A URL -- The endpoint where you want Bitbucket to send the event payloads when a matching event happens.

There are two parts to getting a webhook to work: creating the webhook and triggering the webhook. After you create a webhook for an event, every time that event occurs, Bitbucket sends a payload request that describes the event to the specified URL. Thus, you can think of webhooks as a kind of notification system.

Use webhooks to integrate applications with Bitbucket Cloud. The following use cases provides examples of when you would want to use webhooks:

Every time a user pushes commits in a repository, you may want to notify your CI server to start a build.
Every time a user pushes commits or creates a pull request, you may want to display a notification in your application.

Get a webhook resource

GET /2.0/hook_events

Returns the webhook resource or subject types on which webhooks can be registered.

Each resource/subject type contains an events link that returns the paginated list of specific events each individual subject type can emit.

This endpoint is publicly accessible and does not require authentication or scopes.

Example:

1
2
$ curl https://api.bitbucket.org/2.0/hook_events

{
    "repository": {
        "links": {
            "events": {
                "href": "https://api.bitbucket.org/2.0/hook_events/repository"
            }
        }
    },
    "workspace": {
        "links": {
            "events": {
                "href": "https://api.bitbucket.org/2.0/hook_events/workspace"
            }
        }
    }
}

Request

There are no parameters for this request.

Example

cURL

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://api.bitbucket.org/2.0/hook_events' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200

A mapping of resource/subject types pointing to their individual event types.

Content type	Value
application/json	Subject Types

List subscribable webhook types

GET /2.0/hook_events/{subject_type}

Returns a paginated list of all valid webhook events for the specified entity. The team and user webhooks are deprecated, and you should use workspace instead. For more information, see