Atlassian Bitbucket Post Webhook API
This document contains API description for Post Webhooks for Bitbucket, the main documentation is here.
Version 2
Available since 4.11.25.
REST API base URL: http://localhost:7990/bitbucket/rest/webhook/2.0/configurations
Configuration level
Configuration level depends on "projectKey"
and "repositorySlug"
properties.
1. Global level - properties are not set.
2. Project key - "projectKey"
is set, "repositorySlug"
is not set
3. 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 API)
{
"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
Available before 4.11.25.
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 do this in the global settings.
Last updated: