API 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
CODE

Returns a list of configurations per repository.

Full description at Atlassian Bitbucket Post Webhook API

API 3.5.5 and higher

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
    CODE


    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"
       }
    ]
    CODE

  • Get all configurations for the project

    GET
    /rest/webhook/2.0/configurations?projectKey=$PROJECT
    CODE


    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"
       }
    ]
    CODE

  • Get all configurations for the repository

    GET
    /rest/webhook/2.0/configurations?projectKey=$PROJECT&repositorySlug=$REPOSITORY
    CODE

  • 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"
       }
    ]
    CODE

  • Delete configuration by ID:

    DELETE
    /rest/webhook/2.0/configurations/$ID
    CODE


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

  • Get configuration by ID

    GET
    /rest/webhook/2.0/configurations/$ID
    CODE


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

  • 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"
       }
    CODE


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

  • 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"
       }
    CODE


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

Configuration levels:

Configuration level is defined by two properties in the root of the record:

"projectKey":
"repositorySlug":
CODE

  • Global level

    "projectKey": null
    or
    "projectKey": "b555a433-6a6a-442a-8870-df97c33bb6b" //special constant
    CODE

  • Project level:

    "projectKey": "$PROJECT_KEY"
    CODE

  • Repository level:

    "projectKey": "$PROJECT_KEY",
    "repositorySlug": "$REPOSITORY_SLUG"
    CODE

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 “sources” property.
Example:

  • {
       "projectKey": null,
       "sources": []
    }
    CODE

    Configuration handles the events in all projects/repositories.

  • {
       "projectKey": null,
       "sources": [
           {
           "projectKey": "PROJECT_1"
           },
           {
           "projectKey": "PROJECT_2",
           "repositorySlug": "rep_2"
           }
       ]
    }
    CODE

    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"
           }
       ]
    }
    CODE
    • Configuration handles the events from repositories “rep_1“ and “rep_2“ from the project “PROJECT_1“.

Updated: