Environment WebHooks

Environment Manager is shipped with WebHooks since Version JIRA7-3.4 (only available for JIRA 7.x).

A webhook is a user-defined callback over HTTP. You can use JIRA webhooks to notify any web application (ex : JIRA itself, Confluence, Bamboo, Jenkins,…) when certain Environment events occur in JIRA. For example, you might want to alert your remote web application when a the deployed version or the status of environment is changed, when an new Environment is created, when an new issue is associated to an Environment… Using a webhook to do this means that your remote application doesn’t have to periodically poll JIRA (via the REST APIs) to determine whether changes have occurred.

Learn more about JIRA WebHooks in the Atlassian Documentation here



Environment WebHook Events

The following environment events are available to create new WebHooks in JIRA :

  • Environment Created (a new environment has been created)
  • Environment Edited (an existing environment has been edited)
  • Environment Deleted (an environment has been deleted)
  • Version Deployed (the deployed version of an environment has been changed)
  • Status Updated (the status of an environment has been changed)
  • Issue Associated (an issue has been associated to an environment)
  • Issue Dissociated (an issue has been dissociated to an environment)

Select which event(s) you want to associate to your webhook at the bottom of the WebHooks JIRA admin page :

Apwide TEM WebHooks Events


Environment WebHook URL Variables

You can append variables to the webhook URL when creating or updating a webhook. The variables are listed below :

  • ${environment.id}
  • ${environment.application}
  • ${environment.category}
  • ${environment.deployedVersion}
  • ${environment.status}
  • ${issue.key} (available for Issue Associated and Issue Dissociated)

You can use these variables to dynamically insert the value of the current environment (or issue that fired the event) into the webhook URL when it is triggered.

Note that JIRA 7.x helps you selecting the variable you can use to configure your webhook url :

Apwide TEM WebHooks Listener


Useful Tool to test your WebHooks

There are some free and very useful tools available to help you testing / configuring your webhooks. One of those is : https://requestb.in/ .

It will generate a unique url you can use to configure your webhooks. You can then easily visualize what has been sent by JIRA accessing this unique url with your browser.

Example :

Apwide TEM WebHooks RequestBin Example


Environment WebHook Response Examples

When triggered, Environment WebHook Events post JSON response.

Environment Created response example

{
    "timestamp": 1477302280447,
    "webhookEvent": "environment:created",
    "environment": 
    {
        "id": 3,
        "url": "",
        "urlHtml": "",
        "customProperties": 
        [
            {
                "id": 1,
                "key": "PROPERTY_1",
                "name": "Description",
                "description": "General information about the environment, purpose of the environment,...",
                "active": true,
                "value": "",
                "valueHtml": ""
            },

            {
                "id": 2,
                "key": "PROPERTY_2",
                "name": "Details",
                "description": "Detailed information about the environment (ex : link on admin console, administrator,...)",
                "active": true,
                "value": "",
                "valueHtml": ""
            }
        ],

        "application": 
        {
            "id": 1,
            "name": "eCommerce"
        },

        "category": 
        {
            "id": 1,
            "name": "Dev 1"
        },

        "environmentPermissionScheme": 
        {
            "id": 1,
            "name": "Default EnvironmentPermission Scheme"
        }
    },

    "user": 
    {
        "self": "http://localhost:2990/jira/rest/api/2/user?username=admin",
        "name": "admin",
        "key": "admin",
        "emailAddress": "admin@admin.com",
        "avatarUrls": 
        {
            "48x48": "http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=48",
            "24x24": "http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=24",
            "16x16": "http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=16",
            "32x32": "http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=32"
        },

        "displayName": "admin",
        "active": true,
        "timeZone": "Europe/Zurich"
    }
}

Issue Associated response example

{
    "timestamp": 1477302500095,
    "webhookEvent": "environment:env_customfield_value_added",
    "environment": 
    {
        "id": 1,
        "url": "https://preprod-your-company.com/shop",
        "urlHtml": "<a href=\"https://preprod-your-company.com/shop\" target=\"_blank\">https://preprod-your-comp..</a>",
        "customProperties": 
        [
            {
                "id": 1,
                "key": "PROPERTY_1",
                "name": "Description",
                "description": "General information about the environment, purpose of the environment,...",
                "active": true,
                "value": "PreProd Corporate Shop\nContact:deployment-team@your-company.com\nCalendar:https://preprod-calendar.your-company.com\nCMS access:https://preprod-your-company.com/admin-console",
                "valueHtml": "PreProd Corporate Shop\n<br> Contact:\n<a href=\"mailto:deployment-team@your-company.com\">deployment-team@your-comp..</a>\n<br> Calendar:\n<a href=\"https://preprod-calendar.your-company.com\" target=\"_blank\">https://preprod-calendar...</a>\n<br> CMS access:\n<a href=\"https://preprod-your-company.com/admin-console\" target=\"_blank\">https://preprod-your-comp..</a>"
            },

            {
                "id": 2,
                "key": "PROPERTY_2",
                "name": "Details",
                "description": "Detailed information about the environment (ex : link on admin console, administrator,...)",
                "active": true,
                "value": "DB:Oracle 11.x\nLoadbalanced (4 nodes)\nCDN enabled (Akamai)\nData Refreshed every night",
                "valueHtml": "DB:Oracle 11.x\n<br> Loadbalanced (4 nodes)\n<br> CDN enabled (Akamai)\n<br> Data Refreshed every night"
            }
        ],

        "application": 
        {
            "id": 1,
            "name": "eCommerce"
        },

        "category": 
        {
            "id": 12,
            "name": "PreProd"
        },

        "environmentPermissionScheme": 
        {
            "id": 1,
            "name": "Default EnvironmentPermission Scheme"
        }
    },

    "environmentCustomFieldChange": 
    {
        "field": "Detected In",
        "fieldtype": "custom",
        "from": null,
        "fromString": null,
        "to": "1",
        "toString": "eCommerce PreProd"
    },

    "issueId": 10000,
    "issueKey": "TEST-1",
    "issueType": "Bug",
    "issueSummary": "Checkout is Broken",
    "issueStatus": "To Do",
    "user": 
    {
        "self": "http://localhost:2990/jira/rest/api/2/user?username=admin",
        "name": "admin",
        "key": "admin",
        "emailAddress": "admin@admin.com",
        "avatarUrls": 
        {
            "48x48": "http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=48",
            "24x24": "http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=24",
            "16x16": "http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=16",
            "32x32": "http://www.gravatar.com/avatar/64e1b8d34f425d19e1ee2ea7236d3028?d=mm&s=32"
        },

        "displayName": "admin",
        "active": true,
        "timeZone": "Europe/Zurich"
    }
}