Generate webHooks in Bitbucket Server via REST API for Pipeline Multibranch

Issue

  • I want to create webhooks in Bitbucket server to automatically trigger Multibranch or Bitbucket Team/Project jobs on changes

Environment

Related Issues

Resolution

IMPORTANT: This article was created to workaround the issue JENKINS-38748. This issue has now been resolved. Indeed, since Bitbucket Branch Source 2.1.1 and Post Webhooks for Bitbucket 1.4.1 (Bitbucket add-on), the Bitbucket Branch Source provides the option to automatically register a webhook for your repository/ies. This is the recommended, quicker, easiest configuration. Follow the article How to Trigger Multibranch Jobs from Bitbucket Server for more details.

If you are really not able to upgrade, continue reading for a workaround.

Workaround

A workaround is to use the REST API implemented by the Post Webhooks for Bitbucket. Indeed this add-on exposes a REST API that can be leveraged to create webhooks for your repository/projects in Bitbucket Server. For more information about this REST API, you can see the source code in nl.topicus.bitbucket.api.WebhookResource.

This article provides basic commands that can be used to automate the generation of webhooks until JENKINS-38748 is resolved.

Variables

Following variable are used in this article to make commands as generic as possible. Update them accordingly to match your environment:

  • $USER/$PASSWORD: Username/Password of a Bitbucket user with sufficient permission to create webhooks
  • $BITBUCKET_SERVER_URL: The URL of the Bitbucket Server
  • $PROJECT: The Bitbucket project name
  • $REPO: The Bitbucket repository name
  • $WEBHOOK_ID: The id of an existing Webhook in a Bitbucket repository

The webhook data when POSTing:

  • $TITLE: Title to give to the webhook
  • $ENABLED: true | false
  • $JENKINS_URL: The Jenkins URL

Example in the UI:

Get existing webhooks

Use the following command to get the existing webhooks of a project repository:

curl -u ‘$USER:$PASSWORD’ -H “Content-Type: application/json” -X GET $BITBUCKET_SERVER_URL/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations

This will return the list of existing webhooks in a JSON Array.

Example:

curl -u ‘user:password’ -H “Content-Type: application/json” -X GET https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations

Output:

[{“id”:22,“title”:“Jenkins Example”,“url”:“http://jenkins.example.com/bitbucket-scmsource-hook/notify”,“enabled”:false}]

Create a webhook

Use the following command to create a new webhook for a repository:

curl -u ‘$USER:$PASSWORD’ -H “Content-Type: application/json” -X PUT -d ‘{“title”: “$TITLE”, “url”: “$JENKINS_URL/bitbucket-scmsource-hook/notify”, “enabled”: “$ENABLED”}’ $BITBUCKET_SERVER_URL/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations

This will return the created webhook in a JSON Object.

Example:

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

Output:

{“id”:35,“title”:“http://jenkins.example.com”,“url”:“http://jenkins.example.com/bitbucket-scmsource-hook/notify”,“enabled”:true}

Update a webhook by ID

Use the following command to update an existing webhook of a repository:

curl -u ‘$USER:$PASSWORD’ -H “Content-Type: application/json” -X POST -d ‘{“title”: “$TITLE”, “url”: “$JENKINS_URL/bitbucket-scmsource-hook/notify”, “enabled”: “$ENABLED”}’ $BITBUCKET_SERVER_URL/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations/$WEBHOOK_ID

This will return the updated webhook in a JSON Object.

Example:

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”: “false”}’ https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations/35

Output:

{“id”:35,“title”:“http://jenkins.example.com”,“url”:“http://jenkins.example.com/bitbucket-scmsource-hook/notify”,“enabled”:false}

Delete a webhook by ID

Use the following command to delete an existing webhook of a project repository:

curl -u ‘$USER:$PASSWORD’ -H “Content-Type: application/json” -X DELETE $BITBUCKET_SERVER_URL/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations/$WEBHOOK_ID

This should return nothing unless there is an issue.

Example:

curl -u ‘user:password’ -H “Content-Type: application/json” -X DELETE https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations/35

References

Was this article helpful?
1 out of 2 found this helpful

Have more questions?

5 Comments

Date Votes
  • 0
    Avatar
    K Caola

    Please either update this article or deprecate it as JENKINS-38748 has been resolved.

  • 0
    Avatar
    Allan Burdajewicz

    We will update the article accordingly.

    Thanks for the review.

     

  • 0
    Avatar
    Faizal Rub

    While creating the webhook, how do I set the Repository Events and Pull Request Events via Rest API?  Thanks

  • 0
    Avatar
    Stênio Araújo

    Upvoting what Faizal Rub asked. Is there any way to update the Events via REST API?

  • 0
    Avatar
    Stênio Araújo

    Update

    Atlassian has a documentation for the Post Webhook API, and there it says one is able to set which triggers are used through the REST API.

    Atlassian Bitbucket Post Webhook API - https://moveworkforward.atlassian.net/wiki/spaces/DOCS/pages/867205121/Atlassian+Bitbucket+Post+Webhook+API

Please sign in to leave a comment.