Cloud

Bitbucket Cloud / Reference / REST APIs

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.

Operations

GET/hook_events GET/hook_events/{subject_type}

GET

Get a webhook resource

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.

Request

This request has no parameters.

Responses

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

application/json

Subject Types

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

GET/hook_events

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'

200Response

{
  "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"
      }
    }
  }
}

GET

List subscribable webhook types

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 the announcement.

This is public data that does not require any scopes or authentication.

NOTE: The example response is a truncated response object for the workspace subject_type. We return the same structure for the other subject_type objects.

Request

Path parameters

subject_type

string

Required