Addon
Branch restrictions
Branching model
Commit statuses
Commits
Deployments
Downloads
Issue tracker
Pipelines
Projects
Pullrequests
Refs
Reports
Repositories
Snippets
Source
Ssh
Teams
Users
Webhooks
Workspaces
Other operations

Rate this page:

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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
$ curl https://api.bitbucket.org/2.0/hook_events

{
    "repository": {
        "links": {
            "events": {
                "href": "https://api.bitbucket.org/2.0/hook_events/repository"
            }
        }
    },
    "team": {
        "links": {
            "events": {
                "href": "https://api.bitbucket.org/2.0/hook_events/team"
            }
        }
    },
    "user": {
        "links": {
            "events": {
                "href": "https://api.bitbucket.org/2.0/hook_events/user"
            }
        }
    }
}
OAuth scopes required
None

Request

There are no parameters for this request.

Example

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

Responses

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

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

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

Example:

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
$ curl https://api.bitbucket.org/2.0/hook_events/workspace
{
    "page": 1,
    "pagelen": 30,
    "size": 21,
    "values": [
        {
            "category": "Repository",
            "description": "Whenever a repository push occurs",
            "event": "repo:push",
            "label": "Push"
        },
        {
            "category": "Repository",
            "description": "Whenever a repository fork occurs",
            "event": "repo:fork",
            "label": "Fork"
        },
        {
            "category": "Repository",
            "description": "Whenever a repository import occurs",
            "event": "repo:imported",
            "label": "Import"
        },
        ...
        {
            "category":"Pull Request",
            "label":"Approved",
            "description":"When someone has approved a pull request",
            "event":"pullrequest:approved"
        },
    ]
}
OAuth scopes required
None

Request

Path parameters
subject_type Required

string

A resource or subject type.

Valid values: workspace, user, repository,