Atlassian Bitbucket Post Webhook API

Last updated: Aug 24, 2020

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:

      1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 [ { 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:

      1 2 3 4 5 6 7 8 9 { errors: [ { context: null, message: "Repository iprepo/eric-test3 does not exist.", exceptionName: "com.atlassian.bitbucket.repository.NoSuchRepositoryException" } ] }

      OR

    • Code: 401 UNAUTHORIZED
      Content:

      1 2 3 4 5 6 7 8 9 { "errors": [ { "context": null, "exceptionName": "com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException", "message": "Authentication failed. Please check your credentials and try again." } ] }
  • Sample Call:

    1 curl -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

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 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.' } }
  • Success Response:

    • Code: 201
      Content:

      1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 { 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:

      1 2 3 4 5 6 7 8 9 { "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:

      1 2 3 4 5 6 7 8 9 { "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:

    1 2 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
  • 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

    1 The same is create. Please check above
  • Success Response:

    • Code: 200
      Content:

      1 2 3 4 5 6 7 8 9 { 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:

      1 2 3 4 5 6 7 8 9 { "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:

      1 2 3 4 5 6 7 8 9 { "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:

    1 2 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
  • 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:

      1 2 3 4 5 6 7 8 9 { "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:

      1 Webhook not found
  • Sample Call:

    1 curl -u $USER:$PASSWORD -H Content-Type: application/json -X DELETE $BITBUCKET_SERVER_URL/rest/webhook/1.

Examples

Create a webhook on pull request created or re-scoped.

1 2 3 4 5 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