Overview

Webhooks are aimed to integrate the Release Management app with other software in your organization to create a single and integrated workspace. Typical use cases are the following:

Webhooks configuration is located on the board administration tab.

Create a Hook

In order to create new webhook:

Click “Add webhook“ button.

Webhook creation dialog has two tabs.

Hook definition

Summary tab contains the main properties

Name. The webhook name to be displayed in the table.

Columns. At the moment, the hooks could be triggered only when a release and/or version is moved to a particular column. You are able to choose All or multiple columns from release or version workflows.

In the following version of the Release management app we will add other types of webhook triggers. Such as:

  • Start or release date change for Release and version

  • Summary changed for release or version

  • Comment added or edited

  • Release and version is archived or unarchived

  • Release or version is deleted

  • A version was deployed on the environment or removed from the environment

Please contact us in case you need to speed up the development of the above mentioned features.

Active or Suspended status

You can put Webhook in Active or Suspended status. The later is good fit while you are creating a new one and/or troubleshooting.

Conditions

Hook executes upon move into specific column. You can define additional conditions to check before executing the hook. If one or all conditions (depending on configuration) fails execution will be interrupted.

Thus you can specify conditions by:

Injectable variables in URL

You are able to inject the following variables to the hook URL:

Helpers: JS-like functions for injectable variables

To finetune your web hooks even further you can use JS-like function for injectable variables in URL and Body sections of the hook. Below is a list of functions that could be used:

concat() - concatenates the string arguments to the calling string and returns a new string

{{entity.name.concat('-version')}}

equals() - returns boolean true/false if a calling string matches (exactly) the argument

{{entity.name.equals('version')}}

isEmpty (not exist) - returns boolean true/false if a calling string is empty

{{entity.name.isEmpty()}}

split (string regex) - divides a calling string into an ordered list of substrings by searching for the pattern, puts these substrings into an array, and returns the array. So, you can use .split(pattern)[index] to pickup the right element of the array. If used only .split(pattern) it will return a string of comma separated substrings.

{{entity.name.split(',')[0]}}
{{entity.name.split('_')}}

slice (int beginIndex, int endIndex) - extracts a section of a string and returns it as a new string, without modifying the calling string

{{entity.name.slice(1,5)}}

toLowerCase() - returns the calling string value converted to lower case

{{entity.name.toLowerCase()}}

toUpperCase() - returns the calling string value converted to UPPER case

{{entity.name.toUpperCase()}}

trim() - removes whitespace from both ends of a string and returns a new string, without modifying the original string

{{entity.name.trim()}}

replaceAll (string regex, string replacement) - returns a new string with all matches of regex a replaced by a replacement

{{entity.name.replaceAll(/\d/,'_')}}
note

entity.name above variable is used for example only. Functions are applicable to any string variable from the list.

entity.name above variable is used for example only. Functions are applicable to any string variable from the list.

HTTP calls

Method. HTTP method which will be used for the webhook. Available options are:

URL. The URL which will be called from the Jira server while the webhook execution.

Injectable variables in Body. The variables which could be injected into the body while the webhook execution. The variable list is the same as for URL.

Request body. The request body which will be used while the webhook execution. For instance. it could contact XML or JSON.

Additional headers

On the headers tab, you can define headers for the webhook HTTP request.

The headers could be added in Key-Value format. Multiple headers are supported.

Webhook execution and history

The webhook will be executed if the trigger condition will be fulfilled. In the current version, the condition is a move of release or version to a particular column.

Release management app, will execute outbound HTTP request with the defined parameters and store execution results in the history table.

The history table is available under the hooks list table. In the table, you can see all the webhooks executions for the past 5 days. Older history items will be automatically deleted.

For each history items, the details could be reviewed: - full HTTP request with headers and full HTTP response. This will help to spot and solve any potential problems.

Use cases

Slack Integration

Webhooks could be used for pushing notifications to Slack. Let’s configure the notification for a case when a version is moved to Done status.

Step 1. Navigate to https://api.slack.com/apps?new_app=1 to create an app “From scratch“

Step 2. Choose the name of the App (integration) and a space to send notifications

Step 3. Enable “Incoming Webhooks”

Step 4. Activate it and add new Webhook

Step 5. Allow integration and choose the destination channel from the selected space

Step 6. Copy URL for the Hook

Step 7. Open webhooks configuration in Release management and clone webhook template:

Choose Done column from a version in Columns field and paste received URL on step 6 to URL filed. Save the webhook.

Step 5. Move any version to Done column and observe a notification in the slack channel.

MS Teams integration

Step 1. Go to the channel where you want to add the webhook and select ••• More options from the top navigation bar.

Step 2. Select Connectors from the dropdown menu:

Step 3. Search for Incoming Webhook and select Add.

Step 4. Select Configure, provide a name, and upload an image for your webhook if required:

Step 5. The dialog window presents a unique URL that maps to the channel. Copy and save the webhook URL, to send information to Microsoft Teams and select Done:

Step 6. Open webhooks configuration in Release management and clone [Template] Sample MS Teams Notification:

Choose Done column from a version in Columns field and paste received URL on step 5 to URL filed. Save the webhook.

Step 7. Move any version to Done column and observe a notification in the MS Teams channel.

The webhook is available in the Teams channel.

Use the following code to create Adaptive Card JSON file:

{
   "type":"message",
   "attachments":[
      {
         "contentType":"application/vnd.microsoft.card.adaptive",
         "contentUrl":null,
         "content":{
            "$schema":"http://adaptivecards.io/schemas/adaptive-card.json",
            "type":"AdaptiveCard",
            "version":"1.2",
            "body":[
                {
                "type": "TextBlock",
                "text": "For Samples and Templates, see [https://adaptivecards.io/samples](https://adaptivecards.io/samples)"
                }
            ]
         }
      }
   ]
}

The properties for Adaptive Card JSON file are as follows:

Create Jira Issue

Let’s create a webhook which can help us to create a Jira ticket when a version is moved to UAT status on the board.

The below guide is not super straighforward and requires some advanced skills. We are conssidering options to make it more user friiendly in future versions. For now it just solves the problem & provide and option to create Jira issues

Step 1. Create Atlassian API token.

Step 2. Retrieve required parameters for issue creation, in particular

Click “Create“ to open Create issue dialog in Jira. Select Project and Issue Type you would like to create.

Open the Development Panel in your browse, select Network Tab and click Fetch/XHR button

Create an issue and check “issue“ call

Open Payload and copy ProjectID and IssueTypeID

Step 3. Generate an authorization token (BASE64 token).

Open any site for generating basic authentication base64 string (for instance this one: https://mixedanalytics.com/knowledge-base/api-connector-encode-credentials-to-base-64/)

Enter your username and token from Step 1.

Copy Base 62 authentication spring

For a security reason, we strongly recommend creating a special (different) account for webhooks with just enough permissions to execute required operations. Please don’t use your personal account, especially if it has administrator permissions. Please keep in mind that the token is encoded your login and password in Base64 and it could be decoded back by anybody else. (warning) This method will not protect your credentials

You are able to use more secure methods of authentication in the hooks.

Read more about other authorization methods: https://developer.atlassian.com/cloud/jira/platform/security-for-other-integrations/

Step 4. Create a new WebHook in Release Management App.

Configure the following parameters.

Summary section

Headers section

Jenkins Integration

By using this guide, you can trigger builds in Jenkins remotely as a result of version and/or release appearance in a specific status.

Step 1. Make sure that your Jenkins server is accessible from Jira

Step 2. Create a new user in Jenkins

Step 3. Turn job trigger URL on

Step 4. Configure permissions for the created user

Step 5. Create the URL

More use cases

Please share your cases with us so we can share them here and help others.