How to update settings using REST APIs

Details about configuration updates using REST APIs.

This guide is for Post Webhooks for the Bitbucket Atlassian Marketplace application.

Payload

Here you can find the main configuration JSON schema.

Schema

CODE

{
   "id": int,
   "enabled": bool,
   "name": string,
   "destinations":[
      {
         "useUrl":bool,
         "url": string
      }
   ],
   "sources":[
      {
         "projectKey": string,
         "repositorySlug": string
      }
   ],
   "ignoredSources":[
      {
         "projectKey": string,
         "repositorySlug": string,
         "branchName": string
      }
   ],
   "users":[
      string
   ],
   "ignoredUsers":[
      string
   ],
   "groups":[
      string
   ],
   "ignoredGroups":[
      string
   ],
   "projectKey": string,
   "repositorySlug": string,
   "eventTypes":[
      string
   ],
   "ignoreCerts": bool,
   "ignoreURLValidation": bool,
   "override": bool,
   "skipCI": bool,
   "azureDevOps": bool,
   "payloadType": string,
   "skipPersonalProjects":bool,
   "azureDevOpsToken": string,
   "azureSource": "CLOUD|SERVER",
   "azureSourceBranch": string,
   "azureParameters":[
      string
   ],
         "pushBranches":{
         "branchesToConsider":string,
         "branchesToIgnore":string
      },
      "pullRequestBranches":{
         "fromBranchesToConsider":string,
         "toBranchesToConsider":string,
         "fromBranchesToIgnore":string,
         "toBranchesToIgnore":string},
   "httpMethod": string,
   "enableAuthentication":bool,,
   "authenticationType": "BASIC|BEARER|KERBEROS",
   "authUsername": string,
   "authPassword": string,
   "mutualAuthenticationEnabled":bool,
   "trustStorePassword": string,
   "keyStorePassword": string,
   "trustStore": string,
   "keyStore": string,   
   "filePathPatterns":[
      string
   ],
   "level":string
}

Parameters.

Pair projectKey and repositorySlug define a configuration level.
projectKey is not set and repositorySlug is not set - Global-level configuration affects all repositories in Bitbucket.
projectKey is set and repositorySlug is not set - Project-level configuration, affects all repositories in the given project.
projectKey is set and repositorySlug is set - Repository level configuration.
projectKey and repositorySlug must match the existing project and repositories. Configuration without project
destinations for now can contain only one entry which contains the URL.
payloadType can be one of the Jenkins, Azure, Teams, Bitbucket. Corresponding payload is generated based on the type.

Possible eventTypes values

CODE

"TAG_CREATED",
"BRANCH_DELETED",
"BRANCH_CREATED",
"ABSTRACT_REPOSITORY_REFS_CHANGED",
"PULL_REQUEST_DECLINED",
"PULL_REQUEST_RESCOPED",
"PULL_REQUEST_MERGED",
"PULL_REQUEST_REOPENED",
"PULL_REQUEST_UPDATED",
"PULL_REQUEST_OPENED",
"PULL_REQUEST_COMMENT",
"PULL_REQUEST_CANCELABLE_COMMENT",
"PULL_REQUEST_COMMENT_ACTIVITY",
"PULL_REQUEST_PARTICIPANT_APPROVED",
"BUILD_STATUS_SET",
"REPOSITORY_MIRROR_SYNCHRONIZED",
"PULL_REQUEST_DELETED"

Payload sample

CODE

{
   "id":5,
   "enabled":true,
   "lastModified":1697776537844,
   "name":"Repository1 configuration 1",
   "destinations":[
      {
         "useUrl":true,
         "url":"http://example.com/webhook"
      }
   ],
   "sources":[
      {
         "projectKey":"EVENT_1",
         "repositorySlug":"eve_1"
      }
   ],
   "ignoredSources":[
      {
         "projectKey":"EVENT_1",
         "repositorySlug":"eve_1",
         "branchName":"tttt"
      }
   ],
   "users":[
      "user1"
   ],
   "ignoredUsers":[
      "user2"
   ],
   "groups":[
      
   ],
   "ignoredGroups":[
      
   ],
   "projectKey":"EVENT_1",
   "repositorySlug":"eve_1",
   "eventTypes":[
      "TASK_CREATED",
      "COMMIT_DISCUSSION"
   ],
   "ignoreCerts":false,
   "ignoreURLValidation":false,
   "override":true,
   "skipCI":false,
   "azureDevOps":false,
   "payloadType":"Jenkins",
   "skipPersonalProjects":false,
   "azureSource":"CLOUD",
   "azureParameters":[
      
   ],
   "httpMethod":"POST",
   "enableAuthentication":false,
   "authenticationType":"BASIC",
   "mutualAuthenticationEnabled":false,
   "filePathPatterns":[
      
   ],
   "level":"REPOSITORY"
}

REST API

Create/update configuration

Method POST BITBUCKET_BASE_URL/rest/webhook/latest/configurations

CODE

curl -X POST -u USER:PASSWORD  -H "Content-Type: application/json" BITBUCKET_BASE_URL/rest/webhook/latest/configurations -d \
'{ "name": "Repository1 configuration 1", "destinations": [ {  "url": "http://example.com/webhook" } ], "projectKey": "EVENT_1", "repositorySlug": "eve_1", "eventTypes": [ "TASK_CREATED", "COMMIT_DISCUSSION" ], "payloadType": "Jenkins" }'

Get all configurations

Method GET BITBUCKET_BASE_URL/rest/webhook/latest/configurations

Get Project configurations

Method GET BITBUCKET_BASE_URL/rest/webhook/latest/configurations?projectKey={PROJECT_KEY}

Get Repository configurations

Method GET BITBUCKET_BASE_URL/rest/webhook/latest/configurations?projectKey={PROJECT_KEY}&repositorySlug={REPOSITORY_SLUG}

Search configurations by project/repository, pagination

Method POST BITBUCKET_BASE_URL/rest/webhook/latest/configurations/pagination

Payload schema:

CODE

{
   "projectKey": string,
   "projectPattern" : bool,
   "repositorySlug": string,
   "repositoryPattern": bool
   "limit": int,
   "page": int
}

Sample:

CODE

curl -X POST -u USER:PASSWORD  -H "Content-Type: application/json" BITBUCKET_BASE_URL/bitbucket/rest/webhook/latest/configurations/pagination -d \
'{"projectKey": "PROJECT_KEY_PART","projectPattern" : true,  "limit": 1, "page": 0}'

Get configuration

Method GET BITBUCKET_BASE_URL/rest/webhook/latest/configurations/{ID}

Delete configuration

Method DELETE BITBUCKET_BASE_URL/rest/webhook/latest/configurations/{ID}

Get supported event types

Method GET BITBUCKET_BASE_URL/rest/webhook/latest/configurations/event-types

X-Event-Key header values

Below you can find the map of event types and corresponding Bitbucket X-Event-Key headers.

CODE

PULL_REQUEST_COMMENT_ADDED - pr:comment:added
PULL_REQUEST_COMMENT_EDITED - pr:comment:edited
PULL_REQUEST_COMMENT_DELETED - pr:comment:deleted
PULL_REQUEST_COMMENT_REPLIED - pr:comment:replied
PULL_REQUEST_PARTICIPANT_APPROVED - pr:reviewer:approved
PULL_REQUEST_PARTICIPANT_REVIEWED - pr:reviewer:needs_work
PULL_REQUEST_PARTICIPANT_UNAPPROVED - pr:reviewer:unapproved
PULL_REQUEST_OPENED - pr:opened
PULL_REQUEST_UPDATED - pr:modified
PULL_REQUEST_RESCOPED - pr:modified
PULL_REQUEST_REOPENED - pr:opened
PULL_REQUEST_MERGED - pr:merged
PULL_REQUEST_DECLINED - pr:declined
PULL_REQUEST_DELETED - pr:deleted
PULL_REQUEST_COMMENT - pullrequest:comment
BUILD_STATUS_SET - build:status-set
TAG_CREATED - repo:refs_changed
BRANCH_CREATED - repo:refs_changed
BRANCH_DELETED - repo:refs_changed
REPOSITORY_MIRROR_SYNCHRONIZED - mirror:repo_synchronized
ABSTRACT_REPOSITORY_REFS_CHANGED - repo:refs_changed

Updated: 15 Jul 2024