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:

• Sending notifications. (for instance to Slack, Teams ad etc.)

• Trigger actions in your CI/CD server (for instance trigger build or deployment ). As a result, there is no need to educate all members of your team on how to use CI/CD tools and create separate accounts for them. It could be orchestrated from Release Management App.

• Execute some actions on the same Jira instance (for instance, create a separate Jira issue for integration testing, compliance approval etc). This will open a lot of opportunities on the release workflow automation.

Webhooks configuration is located on the board administration tab.

Open

Create a Hook

In order to create new webhook:

Click “Add webhook“ button.

Webhook creation dialog has two tabs.

• Summary.

• Headers.

Hook definition

Summary tab contains the main properties

Open

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.

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:

• Projects. You can shortlist projects for your Releases and Versions.

• Entities. You can configure it for Releases, Fix Versions, Epic or JQL Version only or a subset of it.

• Properties. You can define specific conditions for your custom properties defined.

Injectable variables in URL

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

• Release or version id

• Release or version name

• Destination column id. Internal id of the column where release or version has been moved. List of columns with their ids you can receive via REST API.

• Destination column name.

• Start date. Release or version start date.

• Release Date.

• Link to release or version. The direct URL to release or version which has triggered the webhook. Such a variable is very convenient for any kink of notifications so the people can navigate to release or version to see the details.

• User name. Full name of a user who has triggered the webhook.

• Custom properties for versions/packages

• Version only variables. They will not be replaced to any value if they will be used on the release context

  • Project name. Name of a parent version project

  • Project Key. Key of a parent version project

  • Project id. Id of a parent version project

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

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

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

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.

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

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

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

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

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

HTTP calls

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

• Get

• Post

• Put

• Delete

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:

The properties for Adaptive Card JSON file are as follows:

• The "type" field must be "message".

• The "attachments" array contains a set of card objects.

• The "contentType" field must be set to Adaptive Card type.

• The "content" object is the card formatted in JSON.

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.

Step 1. Create Atlassian API token.

• Navigate to https://id.atlassian.com/manage-profile/security/api-tokens

• Fill token name (anything you like).

• Store generated token somewhere as it will not be accessible in the future

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

• ProjectID where you want to create issue

• and IssueTypeID of the issue type that you want to create

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

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

Configure the following parameters.

Summary section

• Method: POST

• URL: https://JIRA_INSTANCE_NAME.atlassian.net/rest/api/2/issue

• Body: {"fields":{"summary":"ISSUE_SUMMARY","issuetype":{"id":"YOUR_ISSUE_TYPE_ID_FROM_PREVIOUS_STEP"},"project":{"id":"YOUR_PROJECT_ID_FROM_PREVIOUS_STEP"}}}

Headers section

• Add Authorization header

  1. Key: Authorization

  2. Value: BASE64_TOKEN_FROM_PREVIOUS_STEP

• Add Content-Type header

  1. Key: Content-Type

  2. Value: application/json

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

• Select Manage Jenkins > Manage Users

• Click on Create User

• Fill in the information for your user (I’ll assume you’ve called this user “auto”)

• Click the Sign Up button

Step 3. Turn job trigger URL on

• Click Configure to edit the job. Under Build Triggers, check the box next to “Trigger Builds Remotely”. You’ll be asked to provide a secure token for validation. This should not in any way be related to the user which was created on Step 2, so don’t reuse the password. You might want to generate a new key using a tool like the Random Key Generator. Click Save to save the job information.

Step 4. Configure permissions for the created user

• Select Manage Jenkins > Configure Global Security

• ·Assuming you’re using matrix-based security: add user from Step 2 to the list and check off the boxes:

  • Overall - Read

  • Job - Build

  • Job - Read

  • Job - Workspace

• Click Save

Step 5. Create the URL

• From the user list, find a user from step 2, click on the “configure” icon (the wrench and screwdriver) next to the user name

• Underneath the user’s full name and description is a section labelled “API Token”. Click on the “Show API Token” button. This will reveal the API token you need to provide when triggering a job by URL

• With this information, you can now create a URL that looks like this:
  http://user_name:your_tocken@your_jenkins.com/job/your_job_name/build?token=your_auth_tocken_from_step_3

More use cases

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