Atlassian Bitbucket Post Webhook API
This document contains API description for Post Webhooks for Bitbucket, the main documentation is here.
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:[ { 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 } ]
CODE
Error Response:
Code: 404 NOT FOUND
Content:{ errors: [ { context: null, message: "Repository iprepo/eric-test3 does not exist.", exceptionName: "com.atlassian.bitbucket.repository.NoSuchRepositoryException" } ] }
JSOR
Code: 401 UNAUTHORIZED
Content:{ "errors": [ { "context": null, "exceptionName": "com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException", "message": "Authentication failed. Please check your credentials and try again." } ] }
JS
Sample Call:
curl -u '$USER:$PASSWORD' -H "Content-Type: application/json" -X GET $BITBUCKET_SERVER_URL/rest/webhook/1
CODE
Create post webhook
URL
/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations
Method:
POST
Data Params
schema: { '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.' } }
JSSuccess Response:
Code: 201
Content:{ 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 }
JS
Error Response:
Code: 401 UNAUTHORIZED
Content:{ "errors": [ { "context": null, "exceptionName": "com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException", "message": "Authentication failed. Please check your credentials and try again." } ] }
CODE
OR
Code: 400 BAD REQUEST
Content:{ "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\"])" } ] }
CODE
Sample Call:
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} https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations
CODENotes:
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
The same is create. Please check above
CODESuccess Response:
Code: 200
Content:{ id: 21, title: "Jenkins hook", url: "http://local-jenkins.com/bitbucket-scmsource-hook/notify", committersToIgnore: "jdoe", branchesToIgnore: "", skipCI: true, enabled: true }
CODE
Error Response:
Code: 401 UNAUTHORIZED
Content:{ "errors": [ { "context": null, "exceptionName": "com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException", "message": "Authentication failed. Please check your credentials and try again." } ] }
CODE
OR
Code: 400 BAD REQUEST
Content:{ "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\"])" } ] }
CODE
Sample Call:
curl -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
CODENotes:
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:{ "errors": [ { "context":null, "message":"Authentication failed. Please check your credentials and try again.", "exceptionName":"com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException" } ] }
CODE
OR
Code: 404 NOT FOUND
Content:Webhook not found
CODE
Sample Call:
curl -u $USER:$PASSWORD -H Content-Type: application/json -X DELETE $BITBUCKET_SERVER_URL/rest/webhook/1.
CODE
Examples
Create a webhook on 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 update Old REST APIs?

Last updated: