This document describes an API/Webhook solution for integrating Bitbucket pull request events into the Workcube system using Workcube WEX (Workcube Extension). This integration facilitates the tracking of your business processes and enriches project management by automatically moving the pull request mobility in your development processes into Workcube.

Overview

This WEX component is designed to listen to Pull Request events from Bitbucket and save the relevant data to the Workcube database. In this way, the relevant information becomes automatically accessible in Workcube for each Pull Request opened, updated or closed on Bitbucket.

Purpose: Process the Pull Request data coming from Bitbucket and connect it to the relevant task IDs in Workcube or keep it as a general record.
Technology: A Workcube Extension developed with ColdFusion (CFML). (WEX) component.
How It Works: It is triggered via the Webhook defined in the Bitbucket repository settings. When a Pull Request event comes from Bitbucket, an HTTP POST request is sent to this WEX component and the incoming JSON payload is processed.

API Endpoint Information

The Workcube WEX endpoint you should use in your Bitbucket Webhook settings is below like:

URL:/WEX/bitbucket.cfc?method=ap (This URL is based on the root of your Workcube installation and does not include the server name. For example: https:yourworkcube.com/WEX/bitbucket.cfc?method=ap)
Method:POST
Content Type (Content-Type):application/json

Requirements

WEX (Workcube Extension) module must be installed and active in your Workcube system.
The WEX component mentioned in this document (WEX/bitbucket.cfc) and dependent components (e.g. WEX.bitbucket.components.data) must be deployed on your Workcube server.
This endpoint must be configured correctly under the "Webhooks" settings in your Bitbucket repository. Specifically, make sure that "Pull Request" events are selected.

Operating Logic

The WEX component processes the Pull Request payload from Bitbucket with the following steps:

When a Pull Request event is triggered (create, update, merge, etc.), Bitbucket sends an HTTP POST request to the specified WEX endpoint. The body of this request contains Pull Request information in JSON format.
ap function receives the incoming JSON data (data argument).
It checks whether the pullrequest key is present in the data. If available, it calls the pullrequest function, which is a specific processing function for the Pull Request.
The pullrequest function parses the following information from the incoming JSON data and assigns it to the relevant variables:
- Title: The title of the Pull Request.
- Description: HTML format of the Pull Request. description.
- Task ID: A Workcube Task ID is searched from the Pull Request title or description in the format of numbers starting with the # sign (e.g. #12345). If found, this ID is matched.
- Display URL: URL used to view the Pull Request on Bitbucket.
- Author Information: Name and other details of the user who created the Pull Request.
- Creation Date: Pull Request creation time.
- Bitbucket PR ID: The unique ID that Bitbucket assigns to this Pull Request.
- Destination Branch: The name of the target branch into which the Pull Request will be merged.
- Source Branch: the name of the source branch it comes from.
- State: The current state of the Pull Request (e.g.: OPEN, MERGED, DECLINED).
- Participants: Information about reviewers or other participants in the Pull Request.
This parsed data, It is saved to the Workcube database by calling the insert function in the WEX.bitbucket.components.data component. This is the basic data storage step of the integration.
If the operation is successful, a successful JSON response is returned with result(1). In case of any error, result(0, "", cfcatch) returns a JSON response containing error information.
result function is responsible for returning all processing results in a standard JSON format.

Testing with Postman or Similar Tools

To test this API You can use REST clients like Postman, Insomnia, or cURL. You can simulate a Pull Request event by following these steps:

Method:Select POST
URL: Workcube WEX endpoint (for example: Enter https://yourworkcube.com/WEX/bitbucket.cfc?method=ap).
Headers:Set the Content-Type header to application/json.
Body: Use a real Pull Request JSON payload from Bitbucket. Below is a simple example. Note: This JSON is a simplified version of Bitbucket's actual payload. For a detailed and complete payload, see the Bitbucket documentation or capture it by triggering an actual webhook.

Example Bitbucket Pull Request Payload (Simple)

{

"pullrequest": {

"id": 123,

"title": "New Feature: Workcube Task #9876",

"description": "This pull request adds a new feature. Related Task ID: #9876",

"state": "OPEN",

"created_on": "2023-10-27T10:00:00.000000+00:00",

"links": {

"html": {

"href": "https://bitbucket.org/your_repo/pull-requests/123"

}

},

"author": {

"display_name": "Developer Name"

},

"destination": {

"branch": {

"name": "master"

}

},

"source": {

"branch": {

"name": "feature/new-feature"

}

API Responses

API The JSON responses returned as a result of the call will be in the following formats:

Successful Response

When the operation is completed successfully:

{

"status": 1

}

False Answer

When an error occurs during the operation:

{

"status": 0,

"message": "The error message will be located here.",

"obj": {

"detail": "Error details",

"type": "Error Type"

}

Security Notes

It is recommended that you consider the following methods to secure your Webhooks endpoint:

Restrict your Webhook URL so that only Bitbucket can access it (e.g. IP restrictions via firewall).
By defining a "secret token" for Bitbucket webhooks, you can verify that the incoming request is coming from Bitbucket. You can develop an additional mechanism to verify this token in your WEX component.
Avoid sending sensitive information directly in URL parameters.

Feedback

Did you find this content helpful?

Please Write Your Feedback!

Name*

Last Name*

Email *