Event payloads

In order to improve user privacy in accordance with GDPR regulations, Bitbucket and other Atlassian Cloud products are updating our product APIs to consolidate how we manage access to personal data. These API changes are necessary to support upcoming improvements to Atlassian products that give users greater control over who can see and access their data.

The short summary is that username endpoints and username fields will stop being available on April 12, 2019, and we’re introducing some new data points that are available immediately to replace them. For more information, refer to the API deprecation notice.

When you have a webhook with an event, Bitbucket sends the event request to the server URL for the webhook whenever that event occurs. This page describes the structure of these requests.

For Bitbucket to send event payload requests for a webhook with HTTPS endpoints, make sure your URL has a valid SSL certificate that a public certificate authority has signed.

You may need to know the Bitbucket Cloud IP addresses to allowlist.

The following payloads contain some of the five common entity types– Account, Repository, Issue, Comment, and Pull Request –which have consistent representations in all the payloads where they appear. For example, the actor property in the repo:push payload is a representation of the event's user. The common entities section includes examples of these entities.

HTTP headers

All event payload requests have the following HTTP headers:

HTTP header	Description
X-Event-Key	The event key of the event that triggers the webhook (for example, repo:push).
X-Hook-UUID	The UUID of the webhook that an event triggers. For details about the UUID of a webhook, see the webhook Resource.
X-Request-UUID	The UUID of the request.
X-Attempt-Number	The number of times Bitbucket attempts to send the payload. After the first request, Bitbucket tries to send the payload two more times if the previous attempts fail.

Repository events

You can create webhooks for the following events that occur in a repository.

Push

A user pushes 1 or more commits to a repository. This payload, with an event key of repo:push, provides the following fields:

Parameter	Description
actor	The user who pushed the commits. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The repository with the commits. See the Repository entity sample.
push	The details of the push, which includes the changes property. This property contains an array with all the references that the push updated and the following properties: new: An object containing information about the state of the reference after the push. When a branch is deleted, new is null. new contains these properties: type : The type of reference with the change. branch, or tag for Git repositories. named_branch, bookmark or tag for Mercurial repositories. name: The name of the branch, tag, named branch, or bookmark. target: The details of the most recent commit after the push. links: Links to the reference in the API (self and commits) and on Bitbucket (html). old: An object containing information about the state of the reference before the push. When a branch is created, old is null. old contains these properties: type : The type of reference with the change: branch, tag, or annotated_ tag for Git repositories. named_branch or bookmark for Mercurial repositories. name: The name of the branch, tag, named branch, or bookmark. target: The details of the most recent commit before the push. links: Links to the reference in the API ( self and commits ) and on Bitbucket ( html ). links : Links to the change on Bitbucket (html), in the API (commits), and in the form of a diff (diff). created: true or false to indicate whether the reference is new. closed: true or false to indicate whether the reference is old. forced: true or false to indicate whether the push was forced. commits: An array containing up to 5 of the most recent commits pushed to the reference. The array for a push with more than 5 commits is truncated, which is indicated by the truncated property. In addition to new commits, the array might also include the following commits: Commits that have not been pushed for this reference–If someone created the reference recently, it could have commits that have been pushed to the repository, but they have not been pushed to this specific reference. If that is the case, the array includes these previously pushed commits as well. For example, if you create a new feature branch off of a main branch with a lot of commits, and then you push a single commit to it, the array in the payload contains 5 commits that are all new to the feature branch. These commits include the single commit you just made and the 4 most recent commits of the main branch. Commits that have been force pushed–When you perform a rebase followed by a force push, the commits of the old reference are replaced with all the commits in the new reference. As a result, the array includes the commits part of the new reference. The array does not include commits that are deleted during a rebase or a force push. truncated: true or false to indicate whether Bitbucket truncated the commits array in this payload. The array is truncated when more than 5 commits were pushed. In that case, the commits array includes only the most recent 5 commits.

Parameter

Description

actor

The user who pushed the commits. See the Account entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

repository

The repository with the commits. See the Repository entity sample.

push

The details of the push, which includes the changes property. This property contains an array with all the references that the push updated and the following properties:

new: An object containing information about the state of the reference after the push. When a branch is deleted, new is null. new contains these properties:
- type : The type of reference with the change.
  - branch, or tag for Git repositories.
  - named_branch, bookmark or tag for Mercurial repositories.
- name: The name of the branch, tag, named branch, or bookmark.
- target: The details of the most recent commit after the push.
- links: Links to the reference in the API (self and commits) and on Bitbucket (html).
old: An object containing information about the state of the reference before the push. When a branch is created, old is null. old contains these properties:
- type : The type of reference with the change:
  - branch, tag, or annotated_ tag for Git repositories.
  - named_branch or bookmark for Mercurial repositories.
- name: The name of the branch, tag, named branch, or bookmark.
- target: The details of the most recent commit before the push.
- links: Links to the reference in the API ( self and commits ) and on Bitbucket ( html ).
links : Links to the change on Bitbucket (html), in the API (commits), and in the form of a diff (diff).
created: true or false to indicate whether the reference is new.
closed: true or false to indicate whether the reference is old.
forced: true or false to indicate whether the push was forced.
commits: An array containing up to 5 of the most recent commits pushed to the reference. The array for a push with more than 5 commits is truncated, which is indicated by the truncated property. In addition to new commits, the array might also include the following commits:
- Commits that have not been pushed for this reference–If someone created the reference recently, it could have commits that have been pushed to the repository, but they have not been pushed to this specific reference. If that is the case, the array includes these previously pushed commits as well. For example, if you create a new feature branch off of a main branch with a lot of commits, and then you push a single commit to it, the array in the payload contains 5 commits that are all new to the feature branch. These commits include the single commit you just made and the 4 most recent commits of the main branch.
- Commits that have been force pushed–When you perform a rebase followed by a force push, the commits of the old reference are replaced with all the commits in the new reference. As a result, the array includes the commits part of the new reference. The array does not include commits that are deleted during a rebase or a force push.
truncated: true or false to indicate whether Bitbucket truncated the commits array in this payload. The array is truncated when more than 5 commits were pushed. In that case, the commits array includes only the most recent 5 commits.

repo:push payload

{    
  "actor": Account,
  "repository": Repository,
  "push": {
    "changes": [
      {
        "new": {
          "type": "branch",
          "name": "name-of-branch",
          "target": {
            "type": "commit",
            "hash": "709d658dc5b6d6afcd46049c2f332ee3f515a67d",
            "author": User,
            "message": "new commit message\n",
            "date": "2015-06-09T03:34:49+00:00",
            "parents": [
              {
                "type": "commit",
                "hash": "1e65c05c1d5171631d92438a13901ca7dae9618c",
                "links": {
                  "self": {
                    "href": "https://api.bitbucket.org/2.0/repositories/user_name/repo_name/commit/8cbbd65829c7ad834a97841e0defc965718036a0"
                  },
                  "html": {
                    "href": "https://bitbucket.org/user_name/repo_name/commits/8cbbd65829c7ad834a97841e0defc965718036a0"
                  }
                }
              }
            ],
            "links": {
              "self": {
                "href": "https://api.bitbucket.org/2.0/repositories/user_name/repo_name/commit/c4b2b7914156a878aa7c9da452a09fb50c2091f2"
              },
              "html": {
                "href": "https://bitbucket.org/user_name/repo_name/commits/c4b2b7914156a878aa7c9da452a09fb50c2091f2"
              }
            }
          },
          "links": {
            "self": {
              "href": "https://api.bitbucket.org/2.0/repositories/user_name/repo_name/refs/branches/main"
            },
            "commits": {
              "href": "https://api.bitbucket.org/2.0/repositories/user_name/repo_name/commits/main"
            },
            "html": {
              "href": "https://bitbucket.org/user_name/repo_name/branch/main"
            }
          }
        },
        "old": {
          "type": "branch",
          "name": "name-of-branch",
          "target": {
            "type": "commit",
            "hash": "1e65c05c1d5171631d92438a13901ca7dae9618c",
            "author": User,
            "message": "old commit message\n",
            "date": "2015-06-08T21:34:56+00:00",
            "parents": [
              {
                "type": "commit",
                "hash": "e0d0c2041e09746be5ce4b55067d5a8e3098c843",
                "links": {
                  "self": {
                    "href": "https://api.bitbucket.org/2.0/repositories/user_name/repo_name/commit/9c4a3452da3bc4f37af5a6bb9c784246f44406f7"
                  },
                  "html": {
                    "href": "https://bitbucket.org/user_name/repo_name/commits/9c4a3452da3bc4f37af5a6bb9c784246f44406f7"
                  }
                }
              }
            ],
            "links": {
              "self": {
                "href": "https://api.bitbucket.org/2.0/repositories/user_name/repo_name/commit/b99ea6dad8f416e57c5ca78c1ccef590600d841b"
              },
              "html": {
                "href": "https://bitbucket.org/user_name/repo_name/commits/b99ea6dad8f416e57c5ca78c1ccef590600d841b"
              }
            }
          },
          "links": {
            "self": {
              "href": "https://api.bitbucket.org/2.0/repositories/user_name/repo_name/refs/branches/main"
            },
            "commits": {
              "href": "https://api.bitbucket.org/2.0/repositories/user_name/repo_name/commits/main"
            },
            "html": {
              "href": "https://bitbucket.org/user_name/repo_name/branch/main"
            }
          }
        },
        "links": {
          "html": {
            "href": "https://bitbucket.org/user_name/repo_name/branches/compare/c4b2b7914156a878aa7c9da452a09fb50c2091f2..b99ea6dad8f416e57c5ca78c1ccef590600d841b"
          },
          "diff": {
            "href": "https://api.bitbucket.org/2.0/repositories/user_name/repo_name/diff/c4b2b7914156a878aa7c9da452a09fb50c2091f2..b99ea6dad8f416e57c5ca78c1ccef590600d841b"
          },
          "commits": {
            "href": "https://api.bitbucket.org/2.0/repositories/user_name/repo_name/commits?include=c4b2b7914156a878aa7c9da452a09fb50c2091f2&exclude=b99ea6dad8f416e57c5ca78c1ccef590600d841b"
          }
        },
        "created": false,
        "forced": false,
        "closed": false,
        "commits": [

          {

            "hash": "03f4a7270240708834de475bcf21532d6134777e",

            "type": "commit",

            "message": "commit message\n",

            "author": Account,

            "links": {

              "self": {

                "href": "https://api.bitbucket.org/2.0/repositories/user/repo/commit/03f4a7270240708834de475bcf21532d6134777e"

              },

              "html": {

                "href": "https://bitbucket.org/user/repo/commits/03f4a7270240708834de475bcf21532d6134777e"

              }

            }

          }

        ],

        "truncated": false

      }
    ]
  }
}

Fork

A user forks a repository. This payload, with an event key of repo:fork, provides the following fields:

Parameter	Description
actor	The user who forks the repository. This user is also the owner of the fork. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The original repository that is forked. See the Repository entity sample.
fork	The new repository that is a result of the fork. See the Repository entity sample .

Parameter

Description

actor

The user who forks the repository. This user is also the owner of the fork. See the Account entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

repository

The original repository that is forked. See the Repository entity sample.

fork

The new repository that is a result of the fork. See the Repository entity sample .

repo:fork

{
  "actor": Account,
  "repository": Repository,
  "fork": Repository
}

Updated

A user updates the Name, Description, Website, or Language fields under the Repository details page of the repository settings. This payload, with an event key of repo:updated , provides the following fields:

Parameter	Description
actor	The user who made the update. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The repository updated. See the Repository entity sample.
changes	The details of the change, including the new setting and what it was previously. The payload will only include properties whose values have changed: name: The new Name of the repository and its old name. website: The new Website for the repository and its old website. language: The new Language for the repository and its old language. links: new and old links to the repository's avatar (avatar), the repository in the API (self), and the repository in Bitbucket (html). description: The new Description of the repository and its old description. full_name: The new and old full name of the repository, which includes its team or user account name, a slash (/), and the repository name.

Parameter

Description

actor

The user who made the update. See the Account entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

repository

The repository updated. See the Repository entity sample.

changes

The details of the change, including the new setting and what it was previously. The payload will only include properties whose values have changed:

name: The new Name of the repository and its old name.
website: The new Website for the repository and its old website.
language: The new Language for the repository and its old language.
links: new and old links to the repository's avatar (avatar), the repository in the API (self), and the repository in Bitbucket (html).
description: The new Description of the repository and its old description.
full_name: The new and old full name of the repository, which includes its team or user account name, a slash (/), and the repository name.

repo:updated payload

{
  "actor": Account,
  "repository": Repository,
  "changes": {
    "name": {
"new": "repository",
      "old": "repository_name"
    }
    "website": {
      "new": "http://www.example.com/",
      "old": ""
    }
    "language": {
      "new": "java",
      "old": ""
    }
    "links": {
      "new": {
        "avatar": {
          "href": "https://bitbucket.org/teamawesome/repository/avatar/32/"
        },
        "self": {
          "href": "https://api.bitbucket.org/2.0/repositories/teamawesome/repository"
        }
        "html": {
          "href": "https://bitbucket.org/teamawesome/repository"
        }
      },
      "old": {
        "avatar": {
          "href": "https://bitbucket.org/teamawesome/repository_name/avatar/32/"
        },
        "self": {
          "href": "https://api.bitbucket.org/2.0/repositories/teamawesome/repository_name"
        },
        "html": {
          "href": "https://bitbucket.org/teamawesome/repository_name"
        }
      }
    },
    "description": {
      "new": "This is a better description.",
      "old": "This is a description."
    }
    "full_name": {
      "new": "teamawesome/repository",
      "old": "teamawesome/repository_name"
    }
  }
}

Transfer

A repository transfer is accepted. This with an event key of repo:transfer, provides the following fields:

Parameter	Description
`1actor`	The user who transferred the repository. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
`1repository`	The repository that was transferred. See the Repository entity sample .
`1previous_workspace`	The previous container of the repository. See the Workspace entity sample.

Parameter

Description

actor

The user who transferred the repository. See the Account entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

repository

The repository that was transferred. See the Repository entity sample .

previous_workspace

The previous container of the repository. See the Workspace entity sample.

repo:transfer payload

{
  "actor": Account,
  "repository": Repository,
  "previous_workspace": Workspace
 }     

Commit comment created

A user comments on a commit in a repository. This payload, with an event key of repo:commit_comment_created, provides the following fields:

Parameter	Description
actor	The user who comments on the commit. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
comment	The comment created. See the Comment entity sample.
repository	The repository with the commit. See the Repository entity sample.
commit	The details of the commit, including the hash.

repo:commit_comment_created payload

{
  "actor": Account,
  "comment": Comment,
  "repository": Repository,
  "commit": {
    "hash": "d3022fc0ca3d65c7f6654eea129d6bf0cf0ee08e"
  }
}

Build status created

A build system, CI tool, or another vendor recognizes that a user recently pushed a commit and updates the commit with its status. This payload, with an event key of repo:commit_status_created, provides the following fields:

Parameter	Description
actor	The user who created the commit status. For Bitbucket Connect apps, this is the workspace user that the app is acting on behalf of. See the User entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The repository with the commit. See the Repository entity sample.
commit_status	The details of the commit status, which includes the following properties: name: The name of the commit status. description : The description of the commit status. state: The commit status, which is either INPROGRESS, SUCCESSFUL, or FAILED. key: The key that the system or vendor provides to distinguish the status from other statuses associated with the same commit. url: The URL to the vendor or system that produces the status. type : The type of commit status. Currently, Bitbucket can only associate commit statuses with a build, so the only supported type is build. created_on: The date and time (in ISO 8601 format) the commit status was created. updated_on: The date and time (in ISO 8601 format) the commit status was last updated. links: Links to representations of the commit and commit status in the API or on Bitbucket.

Parameter

Description

actor

The user who created the commit status. For Bitbucket Connect apps, this is the workspace user that the app is acting on behalf of.

See the User entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

repository

The repository with the commit. See the Repository entity sample.

commit_status

The details of the commit status, which includes the following properties:

name: The name of the commit status.
description : The description of the commit status.
state: The commit status, which is either INPROGRESS, SUCCESSFUL, or FAILED.
key: The key that the system or vendor provides to distinguish the status from other statuses associated with the same commit.
url: The URL to the vendor or system that produces the status.
type : The type of commit status. Currently, Bitbucket can only associate commit statuses with a build, so the only supported type is build.
created_on: The date and time (in ISO 8601 format) the commit status was created.
updated_on: The date and time (in ISO 8601 format) the commit status was last updated.
links: Links to representations of the commit and commit status in the API or on Bitbucket.

repo:commit_status_created payload

{
  "actor": Account,
  "repository": Repository,
  "commit_status": {
    "name": "Unit Tests (Python)",
    "description": "Build started",
    "state": "INPROGRESS",
    "key": "mybuildtool",
    "url": "https://my-build-tool.com/builds/MY-PROJECT/BUILD-777",
    "type": "build",
    "created_on": "2015-11-19T20:37:35.547563+00:00",
    "updated_on": "2015-11-19T20:37:35.547563+00:00",

    "links": {
      "commit": {
        "href": "http://api.bitbucket.org/2.0/repositories/tk/test/commit/9fec847784abb10b2fa567ee63b85bd238955d0e"
      },
      "self": {
        "href": "http://api.bitbucket.org/2.0/repositories/tk/test/commit/9fec847784abb10b2fa567ee63b85bd238955d0e/statuses/build/mybuildtool"
      }
    }
  }
}

Build status updated

A build system, CI tool, or another vendor recognizes that a commit has a new status and updates the commit with its status. This payload, with an event key of repo:commit_status_updated, provides the following fields:

Parameter	Description
actor	The user who updated the commit status. For Bitbucket Connect apps, this is the workspace user that the app is acting on behalf of. See the User entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The repository with the commit. See the Repository entity sample.
commit_status	The details of the commit status, which includes the following properties: name: The name of the commit status. description: The description of the commit status. state: The commit status, which is either INPROGRESS, SUCCESSFUL, or FAILED. key: The key that the system or vendor provides to distinguish the status from other statuses associated with the same commit. url: The URL to the vendor or system that produces the status. type: The type of commit status. Currently, Bitbucket can only associate commit statuses with a build, so the only supported type is build. created_on: The date and time (in ISO 8601 format) the commit status was created. updated_on: The date and time (in ISO 8601 format) the commit status was last updated. links: Links to representations of the commit and commit status in the API or on Bitbucket.

Parameter

Description

actor

The user who updated the commit status. For Bitbucket Connect apps, this is the workspace user that the app is acting on behalf of.

See the User entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

repository

The repository with the commit. See the Repository entity sample.

commit_status

The details of the commit status, which includes the following properties:

name: The name of the commit status.
description: The description of the commit status.
state: The commit status, which is either INPROGRESS, SUCCESSFUL, or FAILED.
key: The key that the system or vendor provides to distinguish the status from other statuses associated with the same commit.
url: The URL to the vendor or system that produces the status.
type: The type of commit status. Currently, Bitbucket can only associate commit statuses with a build, so the only supported type is build.
created_on: The date and time (in ISO 8601 format) the commit status was created.
updated_on: The date and time (in ISO 8601 format) the commit status was last updated.
links: Links to representations of the commit and commit status in the API or on Bitbucket.

repo:commit_status_updated payload

{
  "actor": Account,
  "repository": Repository,
  "commit_status": {
    "name": "Unit Tests (Python)",
    "description": "All tests passed",
    "state": "SUCCESSFUL",
    "key": "mybuildtool",
    "url": "https://my-build-tool.com/builds/MY-PROJECT/BUILD-792",
    "type": "build",
    "created_on": "2015-11-19T20:37:35.547563+00:00",
    "updated_on": "2015-11-20T08:01:16.433108+00:00",

    "links": {
      "commit": {
        "href": "http://api.bitbucket.org/2.0/repositories/tk/test/commit/9fec847784abb10b2fa567ee63b85bd238955d0e"
      },
      "self": {
        "href": "http://api.bitbucket.org/2.0/repositories/tk/test/commit/9fec847784abb10b2fa567ee63b85bd238955d0e/statuses/build/mybuildtool"
      }
    }
  }
}

Issue events

You can create webhooks for the following events that occur on an issue.

Created

A user creates an issue for a repository. This payload, with an event key of issue:created, provides the following fields:

Parameter

Description

actor

The user who created the issue. See the Account entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

issue

The issue the user created. See the Issue entity sample.

repository

The repository with the issue. See the Repository entity sample.

issue:created payload

{
  "actor": Account,
  "issue": Issue,
  "repository": Repository
}

Updated

A user updated an issue for a repository. This payload, with an event key of issue:updated, provides the following fields:

Parameter	Description
actor	The user who created the issue. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
issue	The issue the user created. See the Issue entity sample.
repository	The repository with the issue. See the Repository entity sample.
comment	The comment added about the update to the issue. See the Comment entity sample.
changes	The details of the changes to the issue, which includes the following properties: old: The previous value for an issue field. new: The new value for an issue field.

issue:updated payload

{
  "actor": Account,
  "issue": Issue,
  "repository": Repository,

  "comment": Comment,

  "changes": {

    "status": {

      "old": "open",

      "new": "on hold"

    }

  }

}

Comment created

A user comments on an issue associated with a repository. This payload, with an event key of issue:comment_created, provides the following fields:

Parameter	Description
actor	The user who comments on the issue. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The repository with the issue. See the Repository entity sample.
issue	The issue created. See the Issue entity sample.
comment	The comment created. See the Comment entity sample.

issue:comment_created payload

{

  "actor": Account,
  "repository": Repository,
  "issue": Issue,
  "comment": Comment
}

Pull request events

You can create webhooks for the following events that occur on a pull request.

Created

A user creates a pull request for a repository. This payload, with an event key of pullrequest:created, provides the following fields:

Parameter	Description
actor	The user who creates the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
pullrequest	The new pull request. See the Pull Request entity sample.
repository	A representation of the repository with the issue. See the Repository entity sample.

Parameter

Description

actor

The user who creates the pull request. See the Account entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

pullrequest

The new pull request. See the Pull Request entity sample.

repository

A representation of the repository with the issue. See the Repository entity sample.

pullrequest:created payload

{
  "actor": Account,
  "pullrequest": PullRequest,
  "repository": Repository
}

Updated

A user updates a pull request for a repository. This payload, with an event key of pullrequest:updated, provides the following fields:

Parameter	Description
actor	The user who updates the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
pullrequest	The updated pull request. See the Pull Request entity sample.
repository	The repository with the pull request. See the Repository entity sample.

Parameter

Description

actor

The user who updates the pull request. See the Account entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

pullrequest

The updated pull request. See the Pull Request entity sample.

repository

The repository with the pull request. See the Repository entity sample.

pullrequest:updated payload

{
  "actor": Account,
  "pullrequest": PullRequest,
  "repository": Repository
}

Changes Request created

A user requests a change for a pull request for a repository. This payload, with an event key of pullrequest:changes_request_created, provides the following fields:

Parameter	Description
actor	The user who requests a change on the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
pullrequest	The pull request with created change request. See the Pull Request entity sample.
repository	The repository with the pull request. See the Repository entity sample.
changes_request	The details of the change request, including the following properties: date: When the change request was created. user: The user who created the change request.

pullrequest:changes_request_created payload

{
  "actor": Account,
  "pullrequest": PullRequest,
  "repository": Repository,
  "changes_request": {
    "date": "2015-04-06T16:34:59.195330+00:00",
    "user": User
  }
}

Change Request removed

A user removes a change request from a pull request for a repository. This payload, with an event key of pullrequest:changes_request_removed, provides the following fields:

Parameter	Description
actor	The user who removes the requested changes. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
pullrequest	The pull request with the removed change request. See the Pull Request entity sample.
repository	A representation of the repository with the pull request. See the Repository entity sample.
changes_request	The details of the change request, including the following properties: date: When the change request was removed. user: The user who removed the change request.

pullrequest:changes_request_removed payload

{
  "actor": Account,
  "pullrequest": PullRequest,
  "repository": Repository,
  "changes_request": {
    "date": "2015-04-06T16:34:59.195330+00:00",
    "user": User
  }
}

Approved

A user approves a pull request for a repository. This payload, with an event key of pullrequest:approved, provides the following fields:

Parameter	Description
actor	The user who approves the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
pullrequest	The approved pull request. See the Pull Request entity sample.
repository	The repository with the pull request. See the Repository entity sample.
approval	The details of the approval, including the following properties: date: When the approval was created. user: The user who created the approval.

pullrequest:approved payload

{
  "actor": Account,
  "pullrequest": PullRequest,
  "repository": Repository,
  "approval": {
    "date": "2015-04-06T16:34:59.195330+00:00",
    "user": User
  }
}

Approval removed

A user removes an approval from a pull request for a repository. This payload, with an event key of pullrequest:unapproved, provides the following fields:

Parameter	Description
actor	The user who removes the approval. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
pullrequest	The pull request with the removed approval. See the Pull Request entity sample.
repository	A representation of the repository with the pull request. See the Repository entity sample.
approval	The details of the approval, including the following properties: date: When the approval was created. user: The user who created the approval.

pullrequest:unapproved payload

{
  "actor": Account,
  "pullrequest": PullRequest,
  "repository": Repository,
  "approval": {
    "date": "2015-04-06T16:34:59.195330+00:00",
    "user": User
  }
}

Merged

A user merges a pull request for a repository. This payload, with an event key of pullrequest:fulfilled, provides the following fields:

Parameter	Description
actor	The user who merges the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
pullrequest	The merged pull request. See the Pull Request entity sample.
repository	The repository with the pull request. See the Repository entity sample.

Parameter

Description

actor

The user who merges the pull request. See the Account entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

pullrequest

The merged pull request. See the Pull Request entity sample.

repository

The repository with the pull request. See the Repository entity sample.

pullrequest:fulfilled payload

{
  "actor": Account,
  "pullrequest": PullRequest,
  "repository": Repository

}

Declined

A user declines a pull request for a repository. This payload, with an event key of pullrequest:rejected, provides the following fields:

Parameter	Description
actor	The user who declined the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
pullrequest	The declined pull request. See the Pull Request entity sample.
repository	The repository with the pull request. See the Repository entity sample.

Parameter

Description

actor

The user who declined the pull request. See the Account entity sample.

Note: An Account type can be one of three subtypes - User, Team or AppUser.

pullrequest

The declined pull request. See the Pull Request entity sample.

repository

The repository with the pull request. See the Repository entity sample.

pullrequest:rejected payload

{
  "actor": Account,
  "pullrequest": PullRequest,
  "repository": Repository

}

Comment created

A user comments on a pull request. This payload, with an event key of pullrequest:comment_created, provides the following fields:

Parameter	Description
actor	The user who comments on the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The repository with the pull request. See the Repository entity sample.
pull request	The pull request with the comment. See the Pull Request entity sample.
comment	The comment created. See the Comment entity sample.

pullrequest:comment_created payload

{

  "actor": Account,
  "repository": Repository,
  "pullrequest": PullRequest,
  "comment": Comment
}

Comment updated

A user updates a comment on a pull request. If a user updates the same comment with not much time in between, Bitbucket only sends the event request the first time the comment is updated. However, if some time passes and that user updates the comment again, Bitbucket sends the event request a second time.

This payload, with an event key of pullrequest:comment_updated, provides the following fields:

Parameter	Description
actor	The user who updates the comment on the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The repository with the pull request. See the Repository entity sample.
pull request	The pull request with the comment. See the Pull Request entity sample.
comment	The comment updated. See the Comment entity sample.

pullrequest:comment_updated payload

{

  "actor": Account,
  "repository": Repository,
  "pullrequest": PullRequest,
  "comment": Comment
}

Comment deleted

A user deletes a comment on a pull request. This payload, with an event key of pullrequest:comment_deleted, provides the following fields:

Parameter	Description
actor	The user who deletes the comment on the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The repository with the pull request. See the Repository entity sample.
pull request	The pull request with the comment. See the Pull Request entity sample.
comment	The comment deleted. See the Comment entity sample.

pullrequest:comment_deleted payload

{

  "actor": Account,
  "repository": Repository,
  "pullrequest": PullRequest,
  "comment": Comment
}

Comment resolved

A user resolves a comment on a pull request. This payload, with an event key of pullrequest:comment_resolved, provides the following fields:

Parameter	Description
actor	The user who deletes the comment on the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The repository with the pull request. See the Repository entity sample.
pull request	The pull request with the comment. See the Pull Request entity sample.
comment	The comment deleted. See the Comment entity sample.

pullrequest:comment_resolved payload

{
  "actor": Account,
  "repository": Repository,
  "pullrequest": PullRequest,
  "comment": Comment
}

Comment reopened

A user reopens a comment on a pull request. This payload, with an event key of pullrequest:comment_reopened, provides the following fields:

Parameter	Description
actor	The user who deletes the comment on the pull request. See the Account entity sample. Note: An Account type can be one of three subtypes - User, Team or AppUser.
repository	The repository with the pull request. See the Repository entity sample.
pull request	The pull request with the comment. See the Pull Request entity sample.
comment	The comment deleted. See the Comment entity sample.

pullrequest:comment_reopened payload

{
  "actor": Account,
  "repository": Repository,
  "pullrequest": PullRequest,
  "comment": Comment
}

Common entities for event payloads

This section includes examples of how payloads represent users, repositories, issues, comments, or pull requests.

Workspace

The Workspace in event payloads. In addition to the following fields, the workspace entity may include other fields as well.

Parameter	Description
type	Always “workspace”.
slug	The workspace slug used in URLs.
name	The workspace name.
uuid	The universally unique identifier of the workspace.
links	Links to representations of the workspace in the API or on Bitbucket.

Repository

The Repository in event payloads. In addition to the following fields, the repository entity may include other fields as well.

Parameter	Description
type	The property type. In this case, repository .
name	The name of the repository.
full_name	The workspace and repository slugs joined with a '/'.
workspace	The workspace that contains the repository. Set the workspace entity sample.
uuid	The universally unique identifier of the repository.
links	Links to representations of the repository in the API or on Bitbucket.
project	The project that contains the repository (if one does). See the Project entity sample.
website	The URL to the repository's website when the code is hosted for a specific website.
scm	The type repository: Git (git) or Mercurial (hg).
is_private	true or false to indicate whether the repository is private.

Repository property

{

  "type": "repository",

  "links": {
    "self": {
      "href": "https://api.bitbucket.org/api/2.0/repositories/bitbucket/bitbucket"
    },
    "html": {
      "href": "https://api.bitbucket.org/bitbucket/bitbucket"
    },
    "avatar": {
      "href": "https://example.com/avatar.png"
    }
  },
  "uuid": "{673a6070-3421-46c9-9d48-90745f7bfe8e}",

"project": Project,
  "full_name": "workspace_slug/repoitory_slug",

  "workspace": Workspace,
  "name": "repo_name",

  "website": "https://mywebsite.com/",

  "scm": "git",

  "is_private": true
},

Project

The Project in event payloads. In addition to the following fields, the project entity may include other fields as well.

Parameter	Description
type	The property type. For example, project .
name	The Name of the project.
uuid	The universally unique identifier of the user or team.
links	Links to representations of the project's avatar or the project on Bitbucket.
key	The Key of the project.

Project property

{
  "type": "project",

  "project": "Untitled project",
  "uuid": "{3b7898dc-6891-4225-ae60-24613bb83080}",

  "links": {
    "html": {
      "href": "https://bitbucket.org/account/user/teamawesome/projects/proj"
    },
    "avatar": {
      "href": "https://bitbucket.org/account/user/teamawesome/projects/proj/avatar/32"
    }
  },

  "key": "proj"
},

Issue

The Issue in event payloads. In addition to the following fields, the issue entity may include other fields as well.

Parameter	Description
id	The id number of the issue.
component	The component of the issue.
title	The title of the issue.
content	The description of the issue. raw: the raw text as the user typed it markup: the markup language used html: the rendered HTML version of the markup
priority	The priority category of the issue.
state	The status of the issue.
type	The type of issue.
milestone	The milestone reached with the issue.
version	The version number associated with the issue.
created_on	The date and time (in ISO 8601 format) the issue was created.
updated_on	The date and time (in ISO 8601 format) the issue was last updated.
links	Links to representations of the issue in the API or on Bitbucket.

Issue property

{
"id" :  1 ,

   "component" :  "component" ,

   "title" :  "Issue title" ,

   "content" : {

     "raw" :  "Issue description" ,

     "html" :  "<p>Issue description</p>" ,

     "markup" :  "markdown"

   },

   "priority" :  "trivial|minor|major|critical|blocker" ,

   "state" :  "submitted|new|open|on hold|resolved|duplicate|invalid|wontfix|closed" ,

   "type" :  "bug|enhancement|proposal|task" ,

   "milestone" : {  "name" :  "milestone 1" },

   "version" : {  "name" :  "version 1" },

   "created_on" :  "2015-04-06T15:23:38.179678+00:00" ,

   "updated_on" :  "2015-04-06T15:23:38.179678+00:00" ,

  "links": {
    "self": {
      "href": "https://api.bitbucket.org/api/2.0/issues/issue_id"
    },
    "html": {
      "href": "https://api.bitbucket.org/issue_id"
    }
  }

}

Comment

The Comment in event payloads. In addition to the following fields, the comment entity may include other fields as well.

Parameter	Description
id	The id number of the comment.
parent	The id number of the comment's parent comment.
content	The actual comment. It contains the following nested elements: raw: the raw text as the user typed it markup: the markup language used html: the rendered HTML version of the markup
inline	An indication of whether the comment is an inline code comment. It contains the following nested elements: to: the line number of the new version in the diff that the comment was made on (the "green" line). null if the line does not exist in the new version from: the line number of the old version in the diff that the comment was made on (the "red" line). null if the line does not exist in the old version path: the name of the file the comment was made on Inline comments also have an additional link (rel: "code") in the links section that points to the raw file diff.
created_on	The date and time (in ISO 8601 format) the issue was created.
updated_on	The date and time (in ISO 8601 format) the issue was last updated.
links	Links to representations of the comment in the API or on Bitbucket.

Comment property

{
   "id" :  17 ,

   "parent" : {  "id" :  16 },

   "content" : {

     "raw" :  "Comment text" ,

     "html" :  "<p>Comment text</p>" ,

     "markup" :  "markdown" ,

   },

   "inline" : {

     "path" :  "path/to/file" ,

     "from" :  null ,

     "to" :  10

   },

   "created_on" :  "2015-04-06T16:52:29.982346+00:00" ,

   "updated_on" :  "2015-04-06T16:52:29.983730+00:00",

  "links": {
    "self": {
      "href": "https://api.bitbucket.org/api/2.0/comments/comment_id"
    },
    "html": {
      "href": "https://api.bitbucket.org/comment_id"
    }
  }

}

Pull request

The Pull Request in event payloads. In addition to the following fields, the pull request entity may include other fields as well.

Parameter	Description
id	The id number that identifies the pull request.
title	The name of the pull request.
description	The description of the pull request.
state	The status of the pull request.
author	The creator of the pull request.
source	Information about the source of the pull request. It contains the following nested elements: branch: the name of the branch commit: the SHA1 of the branch head repository: the representation of the repository with the branch
destination	Information about the destination of the pull request. It contains the following nested elements: branch: the name of the branch commit: the SHA1 of the branch head repository: the representation of the repository with the branch
merge_commit	The SHA1 of the commit when the pull request merges.
participants	A list of participants part of the pull request.
reviewers	A list of reviewers on the pull request.
close_source_branch	true or false to indicate whether Bitbucket should close the source branch after the pull requests is successfully merged. Only use this parameter when the source and destination are in the same repo.
closed_by	The user who closes the pull request, either by merging or declining it.
reason	The reason the pull request is declined (if necessary).
created_on	The date and time (in ISO 8601 format) the pull request was created.
updated_on	The date and time (in ISO 8601 format) the pull request was last updated.
links	Links to representations of the pull request in the API or on Bitbucket.

Pull Request property

{
   "id" :  1 ,

   "title" :  "Title of pull request" ,

   "description" :  "Description of pull request" ,

   "state" :  "OPEN|MERGED|DECLINED" ,

   "author" : Account,

   "source" : {

     "branch" : {  "name" :  "branch2" },

     "commit" : {  "hash" :  "d3022fc0ca3d" },

     "repository" : Repository

   },

   "destination" : {

     "branch" : {  "name" :  "main" },

     "commit" : {  "hash" :  "ce5965ddd289" },

     "repository" : Repository

   },

   "merge_commit" : {  "hash" :  "764413d85e29" },

   "participants" : [Account],

   "reviewers" : [Account],

   "close_source_branch" :  true ,

   "closed_by" : Account,

   "reason" :  "reason for declining the PR (if applicable)" ,

   "created_on" :  "2015-04-06T15:23:38.179678+00:00" ,

   "updated_on" :  "2015-04-06T15:23:38.205705+00:00",

  "links": {
    "self": {
      "href": "https://api.bitbucket.org/api/2.0/pullrequests/pullrequest_id"
    },
    "html": {
      "href": "https://api.bitbucket.org/pullrequest_id"
    }
  }

}

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community