How to manage configurations using Post Webhooks for Bitbucket APIs?
This guide is for Post Webhooks for the Bitbucket Atlassian Marketplace application.
Managing configurations using the Post Webhooks for Bitbucket APIs allows you to programmatically create, update, retrieve, and delete webhook configurations.
Here's an overview of how to manage configurations using the APIs.
Version 2
REST API base URL: http://localhost:7990/bitbucket/rest/webhook/2.0/configurations
Configuration level
Configuration level depends on "projectKey"
and "repositorySlug"
properties.
Global level - properties are not set.
Project key -
"projectKey"
is set,"repositorySlug"
is not set.Repository level - both properties are set.
Possible event types
TAG_CREATED,
BRANCH_DELETED,
BRANCH_CREATED,
ABSTRACT_REPOSITORY_REFS_CHANGED, -- push event
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_DELETED,
BUILD_STATUS_SET,
REPOSITORY_MIRROR_SYNCHRONIZED
It can be gotten from http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/event-types
Full payload
[
{
"id": 1,
"enabled": true,
"name": "test",
"destinations": [
{
"url": "http://localhost:8080/test"
}
]
"ignoredSources": [],
"users": [],
"ignoredUsers": [],
"groups": [],
"ignoredGroups": [],
"projectKey": "PROJECT_1",
"repositorySlug": "rep_1",
"eventTypes": [
"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_DELETED",
"BUILD_STATUS_SET",
"REPOSITORY_MIRROR_SYNCHRONIZED"
],
"pullRequestBranchSource": "FROM",
"ignoreCerts": false,
"ignoreURLValidation": false,
"override": true,
"skipCI": true,
"azureDevOps": false,
"skipPersonalProjects": false,
"azureDevOpsToken": "xxxxxx",
"azureSource": "CLOUD",
"azureSourceBranch": "",
"azureParameters": [],
"httpMethod": "POST",
"enableAuthentication": false,
"authenticationType": "BASIC",
"authUsername": "",
"authPassword": "xxxxxx",
"mutualAuthenticationEnabled": false,
"trustStorePassword": "",
"keyStorePassword": "",
"trustStore": "",
"keyStore": "",
"repositoryPattern": "",
"filePathPatterns": []
}
]
Smallest payload
The smallest payload which can be used (corresponding to the Version 1)
{
"enabled": true,
"name": "test",
"destinations": [
{
"url": "http://localhost:8080/test"
}
],
"projectKey": "PROJECT_1",
"repositorySlug": "rep_1",
"eventTypes": [
"TAG_CREATED",
"BRANCH_DELETED",
"BRANCH_CREATED",
"ABSTRACT_REPOSITORY_REFS_CHANGED"
]
}
Get configurations
projectKey
,repositorySlug
- optional parameters
Create configuration
POST http://localhost:7990/bitbucket/rest/webhook/2.0/configurations payload
Update configuration
PUT http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/ID payload
Delete configuration
DELETE http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/ID
Disable batch of configurations
PUT http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/disable?bulkIds=ID1,ID2,ID3
Enable batch of configurations
PUT http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/enable?bulkIds=ID1,ID2,ID3
Delete a batch of configurations
DELETE http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/delete?bulkIds=ID1,ID2,ID3
Version 1
Get existing post webhooks for a specified project
URL
/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations
Method
GET
Response
Success Response:
Code: 200
Content:CODE[ { id: 21, title: "Jenkins hook", url: "http://local-jenkins.com/bitbucket-scmsource-hook/notify", committersToIgnore: "jdoe", branchesToIgnore: "release/*", enabled: true, skipCI: true, tagCreated: true, branchDeleted: true, branchCreated: true, repoPush: true, prDeclined: true, prRescoped: true, prMerged: true, prReopened: true, prUpdated: true, prCreated: true, prCommented: true, prDeleted: true, buildStatus: true, repoMirrorSynced: true }, { id: 642, title: "Other Site hook", url: "http://local-site.com/path/to/hook", skipCI: falsem enabled: true } ]
Error Response:
Code: 404 NOT FOUND
Content:JS{ errors: [ { context: null, message: "Repository iprepo/eric-test3 does not exist.", exceptionName: "com.atlassian.bitbucket.repository.NoSuchRepositoryException" } ] }
OR
Code: 401 UNAUTHORIZED
Content:JS{ "errors": [ { "context": null, "exceptionName": "com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException", "message": "Authentication failed. Please check your credentials and try again." } ] }
Sample Call:
CODEcurl -u '$USER:$PASSWORD' -H "Content-Type: application/json" -X GET $BITBUCKET_SERVER_URL/rest/webhook/1
Create post webhook
URL
/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations
Method:
POST
Data Params
JSschema: { 'title': { 'type': 'string', 'description': 'The title of the post webhook - used for naming only.' }, 'url': { 'type': 'string', 'description': 'The url of the webhook.' }, 'enabled': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is enabled.' }, 'committersToIgnore': { 'type': 'string', 'description': "Comma separated list of user ids in bitbucket to ignore commits from for triggering the webhook" }, 'branchesToIgnore': { 'type': 'string', 'description': "Comma separated list of branch masks to ignore notifications from" }, 'skipCI': { 'type': 'boolean', 'description': 'Do not post webhooks if the title or description of a PR, or the last commit message contain "[ci skip]" or "[skip ci]".' }, 'tagCreated': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on tag created event.' }, 'branchDeleted': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on branch deleted event.' }, 'branchCreated': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on branch created event.' }, 'repoPush': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on repository pushed event.' }, 'prDeclined': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on pull request declined event.' }, 'prRescoped': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on pull request rescoped event.' }, 'prMerged': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on pull request merged event.' }, 'prReopened': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on pull request opened event.' }, 'prUpdated': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on pull request updated event.' }, 'prCreated': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on pull request created event.' }, 'prCommented': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on pull request commented event.' }, 'prDeleted': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on branch created event.' }, 'buildStatus': { 'type': 'boolean', 'description': 'Toggle whether or not the webhook is sent on build status channged event.' } }
Success Response:
Code: 201
Content:JS{ id: 21, title: "Jenkins hook", url: "http://local-jenkins.com/bitbucket-scmsource-hook/notify", committersToIgnore: "jdoe", branchesToIgnore: "", skipCI: true, enabled: true // the events are set as below } // OR the below request { id: 21, title: "Jenkins hook", url: "http://local-jenkins.com/bitbucket-scmsource-hook/notify", committersToIgnore: "jdoe", branchesToIgnore: "", enabled: true, skipCI: true, tagCreated: false, branchDeleted: true, branchCreated: true, repoPush: true, prDeclined: true, prRescoped: true, prMerged: true, prReopened: true, prUpdated: true, prCreated: true, prCommented: false, prDeleted: false, buildStatus: false, repoMirrorSynced: false }
Error Response:
Code: 401 UNAUTHORIZED
Content:CODE{ "errors": [ { "context": null, "exceptionName": "com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException", "message": "Authentication failed. Please check your credentials and try again." } ] }
OR
Code: 400 BAD REQUEST
Content:CODE{ "errors": [ { "context": "fake_field", "exceptionName": null, "message": "Unrecognized field \"fake_field\" (Class nl.topicus.bitbucket.api.WebHookConfigurationModel), not marked as ignorable\n at [Source: com.atlassian.stash.internal.web.util.web.CountingServletInputStream@527f4356; line: 3, column: 16] (through reference chain: nl.topicus.bitbucket.api.WebHookConfigurationModel[\"titlee\"])" } ] }
Sample Call:
CODEcurl -u user:password -H Content-Type: application/json -X POST -d {title: http://jenkins.example.com, url: http://jenkins.example.com/bitbucket-scmsource-hook/notify, enabled: true} https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations
Notes:
This endpoint, the creation of a post webhook, can also be called as a 'PUT' request to maintain backward compatibility. However, The proper API verb for the creation of a new resource is 'POST'
Update a post webhook by ID
URL
/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations/$WEBHOOK_ID
Method:
PUT
Data Params
CODEThe same is create. Please check above
Success Response:
Code: 200
Content:CODE{ id: 21, title: "Jenkins hook", url: "http://local-jenkins.com/bitbucket-scmsource-hook/notify", committersToIgnore: "jdoe", branchesToIgnore: "", skipCI: true, enabled: true }
Error Response:
Code: 401 UNAUTHORIZED
Content:CODE{ "errors": [ { "context": null, "exceptionName": "com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException", "message": "Authentication failed. Please check your credentials and try again." } ] }
OR
Code: 400 BAD REQUEST
Content:CODE{ "errors": [ { "context": "fake_field", "exceptionName": null, "message": "Unrecognized field \"fake_field\" (Class nl.topicus.bitbucket.api.WebHookConfigurationModel), not marked as ignorable\n at [Source: com.atlassian.stash.internal.web.util.web.CountingServletInputStream@527f4356; line: 3, column: 16] (through reference chain: nl.topicus.bitbucket.api.WebHookConfigurationModel[\"titlee\"])" } ] }
Sample Call:
CODEcurl -u user:password -H Content-Type: application/json -X PUT -d {title: http://jenkins.example.com, url: http://jenkins.example.com/bitbucket-scmsource-hook/notify, enabled: true} https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations
Notes:
This endpoint, the update of an existing post webhook, can also be called as a 'POST' request to maintain backward compatibility. However, The proper API verb for updates to an existing resource is 'PUT'
Delete a post webhook by ID
URL
/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations/$WEBHOOK_ID
Method:
DELETE
Success Response:
Code: 204
Error Response:
Code: 401 UNAUTHORIZED
Content:CODE{ "errors": [ { "context":null, "message":"Authentication failed. Please check your credentials and try again.", "exceptionName":"com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException" } ] }
OR
Code: 404 NOT FOUND
Content:CODEWebhook not found
Sample Call:
CODEcurl -u $USER:$PASSWORD -H Content-Type: application/json -X DELETE $BITBUCKET_SERVER_URL/rest/webhook/1.
Examples
Create a webhook on the pull request created or re-scoped.
curl -u user:password \
-H Content-Type: application/json \
-X POST \
-d {title: http://jenkins.example.com, url: http://jenkins.example.com/bitbucket-scmsource-hook/notify, enabled: true, skipCI: true, prCreated: true, prRescoped: true } \
https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations
How to disable Old REST APIs?
You can disable Old REST APIs on the Global configuration page:
Move to the Bitbucket Administration section (“gear” button in the right corner of the navigation menu).
Navigate to the Add-ons section and find our application Post Webhooks.
On the Global Configuration page, navigate to the Global Settings tab.
Tick the checkbox Disable Old Rest API and click on the Save button.
Last updated: