This guide is for the Post Webhooks for Bitbucket Atlassian Marketplace application.
API for 2.5.3 and lower versions
Prior to version 3.5.5 configurations exist only at the repository level and there is no API to get all available configurations at one REST call.
API:
/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations
Returns a list of configurations per repository.
Full description at Atlassian Bitbucket Post Webhook API
API for 3.5.5 and newer versions
All operations respect user permissions. If the user doesn’t have permissions to a project/repository he can’t get/save/update/delete configurations at particular levels.
-
Get all configurations:
GET /rest/webhook/2.0/configurations
Response:
[ { "id":2, "enabled":true, "name":"test", "destinations":[ { "useUrl":false, "url":"http://localhost:8080/test" } ], "sources":[ { "projectKey":"PROJECT_1", "repositorySlug":"rep_1" } ], "ignoredSources":[ ], "users":[ ], "ignoredUsers":[ ], "groups":[ ], "ignoredGroups":[ ], "projectKey":"PROJECT_1", "repositorySlug":"rep_1", "eventTypes":[ "TAG_CREATED", "BRANCH_DELETED", "ABSTRACT_REPOSITORY_REFS_CHANGED", "PULL_REQUEST_OPENED", "PULL_REQUEST_COMMENT", "PULL_REQUEST_CANCELABLE_COMMENT", "PULL_REQUEST_COMMENT_ACTIVITY" ], "pullRequestBranchSource":"FROM", "ignoreCerts":false, "ignoreURLValidation":false, "override":true, "skipCI":false, "azureDevOps":false, "skipPersonalProjects":false, "azureSource":"CLOUD", "httpMethod":"POST", "enableAuthentication":false, "authenticationType":"BASIC", "mutualAuthenticationEnabled":false, "type":"NOTIFICATION" } ]
-
Get all configurations for the project
GET /rest/webhook/2.0/configurations?projectKey=$PROJECT
Response:
[ { "id":2, "enabled":true, "name":"test", "destinations":[ { "useUrl":false, "url":"http://localhost:8080/test" } ], "sources":[ { "projectKey":"PROJECT_1", "repositorySlug":"rep_1" } ], "ignoredSources":[ ], "users":[ ], "ignoredUsers":[ ], "groups":[ ], "ignoredGroups":[ ], "projectKey":"PROJECT_1", "repositorySlug":"rep_1", "eventTypes":[ "TAG_CREATED", "BRANCH_DELETED", "ABSTRACT_REPOSITORY_REFS_CHANGED", "PULL_REQUEST_OPENED", "PULL_REQUEST_COMMENT", "PULL_REQUEST_CANCELABLE_COMMENT", "PULL_REQUEST_COMMENT_ACTIVITY" ], "pullRequestBranchSource":"FROM", "ignoreCerts":false, "ignoreURLValidation":false, "override":true, "skipCI":false, "azureDevOps":false, "skipPersonalProjects":false, "azureSource":"CLOUD", "httpMethod":"POST", "enableAuthentication":false, "authenticationType":"BASIC", "mutualAuthenticationEnabled":false, "type":"NOTIFICATION" } ]
-
Get all configurations for the repository
GET /rest/webhook/2.0/configurations?projectKey=$PROJECT&repositorySlug=$REPOSITORY
-
Response:
[ { "id":2, "enabled":true, "name":"test", "destinations":[ { "useUrl":false, "url":"http://localhost:8080/test" } ], "sources":[ { "projectKey":"PROJECT_1", "repositorySlug":"rep_1" } ], "ignoredSources":[ ], "users":[ ], "ignoredUsers":[ ], "groups":[ ], "ignoredGroups":[ ], "projectKey":"PROJECT_1", "repositorySlug":"rep_1", "eventTypes":[ "TAG_CREATED", "BRANCH_DELETED", "ABSTRACT_REPOSITORY_REFS_CHANGED", "PULL_REQUEST_OPENED", "PULL_REQUEST_COMMENT", "PULL_REQUEST_CANCELABLE_COMMENT", "PULL_REQUEST_COMMENT_ACTIVITY" ], "pullRequestBranchSource":"FROM", "ignoreCerts":false, "ignoreURLValidation":false, "override":true, "skipCI":false, "azureDevOps":false, "skipPersonalProjects":false, "azureSource":"CLOUD", "httpMethod":"POST", "enableAuthentication":false, "authenticationType":"BASIC", "mutualAuthenticationEnabled":false, "type":"NOTIFICATION" } ]
-
Delete configuration by ID:
DELETE /rest/webhook/2.0/configurations/$ID
Response:
{ "id":2, "enabled":true, "name":"test", "destinations":[ { "useUrl":false, "url":"http://localhost:8080/test" } ], "sources":[ { "projectKey":"PROJECT_1", "repositorySlug":"rep_1" } ], "ignoredSources":[ ], "users":[ ], "ignoredUsers":[ ], "groups":[ ], "ignoredGroups":[ ], "projectKey":"PROJECT_1", "repositorySlug":"rep_1", "eventTypes":[ "TAG_CREATED", "BRANCH_DELETED", "ABSTRACT_REPOSITORY_REFS_CHANGED", "PULL_REQUEST_OPENED", "PULL_REQUEST_COMMENT", "PULL_REQUEST_CANCELABLE_COMMENT", "PULL_REQUEST_COMMENT_ACTIVITY" ], "pullRequestBranchSource":"FROM", "ignoreCerts":false, "ignoreURLValidation":false, "override":true, "skipCI":false, "azureDevOps":false, "skipPersonalProjects":false, "azureSource":"CLOUD", "httpMethod":"POST", "enableAuthentication":false, "authenticationType":"BASIC", "mutualAuthenticationEnabled":false, "type":"NOTIFICATION" }
-
Get configuration by ID
GET /rest/webhook/2.0/configurations/$ID
Response:
{ "id":2, "enabled":true, "name":"test", "destinations":[ { "useUrl":false, "url":"http://localhost:8080/test" } ], "sources":[ { "projectKey":"PROJECT_1", "repositorySlug":"rep_1" } ], "ignoredSources":[ ], "users":[ ], "ignoredUsers":[ ], "groups":[ ], "ignoredGroups":[ ], "projectKey":"PROJECT_1", "repositorySlug":"rep_1", "eventTypes":[ "TAG_CREATED", "BRANCH_DELETED", "ABSTRACT_REPOSITORY_REFS_CHANGED", "PULL_REQUEST_OPENED", "PULL_REQUEST_COMMENT", "PULL_REQUEST_CANCELABLE_COMMENT", "PULL_REQUEST_COMMENT_ACTIVITY" ], "pullRequestBranchSource":"FROM", "ignoreCerts":false, "ignoreURLValidation":false, "override":true, "skipCI":false, "azureDevOps":false, "skipPersonalProjects":false, "azureSource":"CLOUD", "httpMethod":"POST", "enableAuthentication":false, "authenticationType":"BASIC", "mutualAuthenticationEnabled":false, "type":"NOTIFICATION" }
-
Save configuration
POST /rest/webhook/2.0/configurations Body: { "enabled":true, "name":"test", "destinations":[ { "useUrl":false, "url":"http://localhost:8080/test" } ], "sources":[ { "projectKey":"PROJECT_1", "repositorySlug":"rep_1" } ], "ignoredSources":[ ], "users":[ ], "ignoredUsers":[ ], "groups":[ ], "ignoredGroups":[ ], "projectKey":"PROJECT_1", "repositorySlug":"rep_1", "eventTypes":[ "TAG_CREATED", "BRANCH_DELETED", "ABSTRACT_REPOSITORY_REFS_CHANGED", "PULL_REQUEST_OPENED", "PULL_REQUEST_COMMENT", "PULL_REQUEST_CANCELABLE_COMMENT", "PULL_REQUEST_COMMENT_ACTIVITY" ], "pullRequestBranchSource":"FROM", "ignoreCerts":false, "ignoreURLValidation":false, "override":true, "skipCI":false, "azureDevOps":false, "skipPersonalProjects":false, "azureSource":"CLOUD", "httpMethod":"POST", "enableAuthentication":false, "authenticationType":"BASIC", "mutualAuthenticationEnabled":false, "type":"NOTIFICATION" }
Response:
{ "id":2, "enabled":true, "name":"test", "destinations":[ { "useUrl":false, "url":"http://localhost:8080/test" } ], "sources":[ { "projectKey":"PROJECT_1", "repositorySlug":"rep_1" } ], "ignoredSources":[ ], "users":[ ], "ignoredUsers":[ ], "groups":[ ], "ignoredGroups":[ ], "projectKey":"PROJECT_1", "repositorySlug":"rep_1", "eventTypes":[ "TAG_CREATED", "BRANCH_DELETED", "ABSTRACT_REPOSITORY_REFS_CHANGED", "PULL_REQUEST_OPENED", "PULL_REQUEST_COMMENT", "PULL_REQUEST_CANCELABLE_COMMENT", "PULL_REQUEST_COMMENT_ACTIVITY" ], "pullRequestBranchSource":"FROM", "ignoreCerts":false, "ignoreURLValidation":false, "override":true, "skipCI":false, "azureDevOps":false, "skipPersonalProjects":false, "azureSource":"CLOUD", "httpMethod":"POST", "enableAuthentication":false, "authenticationType":"BASIC", "mutualAuthenticationEnabled":false, "type":"NOTIFICATION" }
-
Update configuration
PUT /rest/webhook/2.0/configurations/$ID Body: { "enabled":true, "name":"test", "destinations":[ { "useUrl":false, "url":"http://localhost:8080/test" } ], "sources":[ { "projectKey":"PROJECT_1", "repositorySlug":"rep_1" } ], "ignoredSources":[ ], "users":[ ], "ignoredUsers":[ ], "groups":[ ], "ignoredGroups":[ ], "projectKey":"PROJECT_1", "repositorySlug":"rep_1", "eventTypes":[ "TAG_CREATED", "BRANCH_DELETED", "ABSTRACT_REPOSITORY_REFS_CHANGED", "PULL_REQUEST_OPENED", "PULL_REQUEST_COMMENT", "PULL_REQUEST_CANCELABLE_COMMENT", "PULL_REQUEST_COMMENT_ACTIVITY" ], "pullRequestBranchSource":"FROM", "ignoreCerts":false, "ignoreURLValidation":false, "override":true, "skipCI":false, "azureDevOps":false, "skipPersonalProjects":false, "azureSource":"CLOUD", "httpMethod":"POST", "enableAuthentication":false, "authenticationType":"BASIC", "mutualAuthenticationEnabled":false, "type":"NOTIFICATION" }
Response:
{ "id":2, "enabled":true, "name":"test", "destinations":[ { "useUrl":false, "url":"http://localhost:8080/test" } ], "sources":[ { "projectKey":"PROJECT_1", "repositorySlug":"rep_1" } ], "ignoredSources":[ ], "users":[ ], "ignoredUsers":[ ], "groups":[ ], "ignoredGroups":[ ], "projectKey":"PROJECT_1", "repositorySlug":"rep_1", "eventTypes":[ "TAG_CREATED", "BRANCH_DELETED", "ABSTRACT_REPOSITORY_REFS_CHANGED", "PULL_REQUEST_OPENED", "PULL_REQUEST_COMMENT", "PULL_REQUEST_CANCELABLE_COMMENT", "PULL_REQUEST_COMMENT_ACTIVITY" ], "pullRequestBranchSource":"FROM", "ignoreCerts":false, "ignoreURLValidation":false, "override":true, "skipCI":false, "azureDevOps":false, "skipPersonalProjects":false, "azureSource":"CLOUD", "httpMethod":"POST", "enableAuthentication":false, "authenticationType":"BASIC", "mutualAuthenticationEnabled":false, "type":"NOTIFICATION" }
Configuration levels
Configuration level is defined by two properties in the root of the record:
"projectKey":
"repositorySlug":
-
Global level
"projectKey": null or "projectKey": "b555a433-6a6a-442a-8870-df97c33bb6b" //special constant
-
Project level:
"projectKey": "$PROJECT_KEY"
-
Repository level:
"projectKey": "$PROJECT_KEY", "repositorySlug": "$REPOSITORY_SLUG"
Configuration affections
Configuration can affect only specific projects/repositories. By default configuration affect the level at which it's specified but the scope can be narrowed by providing the “sources” property.
Example:
{
"projectKey": null,
"sources": []
}
-
Configuration handles the events in all projects/repositories.
{
"projectKey": null,
"sources": [
{
"projectKey": "PROJECT_1"
},
{
"projectKey": "PROJECT_2",
"repositorySlug": "rep_2"
}
]
}
-
Configuration handles the events in all repositories from “PROJECT_1“ and repository “rep_2“ from the project “PROJECT_2“.
{
"projectKey": PROJECT_1,
"sources": [
{
"projectKey": "PROJECT_1",
"repositorySlug": "rep_1"
},
{
"projectKey": "PROJECT_1",
"repositorySlug": "rep_2"
}
]
}
-
Configuration handles the events from repositories “rep_1“ and “rep_2“ from the project “PROJECT_1“.
How to set up Azure DevOps Pipeline triggering from Bitbucket Server?
How to enable notifications from Bitbucket in Microsoft Teams?
Global Configurations for Bitbucket admins
Repository Level Configurations
Updated: