Generate webHooks in Bitbucket Server via REST API for Pipeline Multibranch

Article ID:115000083932
2 minute readKnowledge base

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.

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:

post webhooks for bitbucket

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":"https://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": "https://jenkins.example.com", "url": "https://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":"https://jenkins.example.com","url":"https://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": "https://jenkins.example.com", "url": "https://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":"https://jenkins.example.com","url":"https://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