Last updated:

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

      OR

    • 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.'
        }
    }
    JS
  • Success 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
    
    CODE
  • 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

    The same is create. Please check above
    CODE
  • Success 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
    
    CODE
  • 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:

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