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

How to update Old REST APIs?

Last updated: