Setting up Webhook Integration

Summary

Through Elevators notification channels your team can subscribe to webhooks that keep you notified as Elevator is updating issues.

Webhooks are triggered whenever Elevator for JIRA Escalates, Re-escalates, Assigns, Acknowledges or Completes and issue. These events are triggered by your JIRA users, workflow automation or background worker processes.

Webhooks will provide data about the event and let your systems react with this data.

Webhook Data

Elevator for JIRA will send a POST request to the webhook url with a JSON body of data.

The body is broken up into 4 main components:

Escalation	The current state of the Elevator escalation or assignment.
Event	The event that triggered the change.
Issue	Basic information of the JIRA issue.
Links	Provides links to further action the issue where applicable.

Detailed Schema

The schema for webhook data is detailed as a standard http://json-schema.org/ schema

JSON Schema for Elevator Webhooks

{
  "description": "Elevator for JIRA webhook schema. http://json-schema.org/",
  "id": "http://www.elevatorforjira.com/schemas/1.0.0/notification-webhook.json",
  "type": "object",
  "properties": {
    "escalation": {
      "description": "Details of the ongoing escalation",
      "type": "object",
      "properties": {
        "id": {
          "description": "Unique identifier for the escalation",
          "type": "integer"
        },
        "initiator": {
          "description": "The original initiator of the escalation",
          "$ref": "#/definitions/initiator"
        },
        "isReEscalated": {
          "description": "True if the original escalation has been re-escalated."
        },
        "reEscalationInitiator": {
          "description": "The last initiator of the re-escalation",
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/definitions/initiator"
            }
          ]
        },
        "fromState": {
          "description": "The state of the escalation before the event occurred",
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/definitions/escalationState"
            }
          ]
        },
        "toState": {
          "description": "The state of the escalation after the event occurred",
          "$ref": "#/definitions/escalationState"
        },
        "fromRoster": {
          "description": "The roster that the issue was assigned to before the event occurred",
          "oneOf": [
            {
              "type": "null"
            },
            {
              "$ref": "#/definitions/elevatorRoster"
            }
          ]
        },
        "toRoster": {
          "description": "The roster that the issue was assigned to after the event occurred",
          "$ref": "#/definitions/elevatorRoster"
        }
      },
      "required": [
        "id",
        "initiator",
        "isReEscalated",
        "toState",
        "toRoster"
      ]
    },
    "event": {
      "description": "Details of the triggered event",
      "type": "object",
      "properties": {
        "id": {
          "description": "Unique identifier for the event",
          "type": "integer"
        },
        "type": {
          "description": "The type of event that has occurred",
          "type": "string",
          "enum": [
            "ESCALATED",
            "REESCALATED",
            "ACKNOWLEDGED",
            "COMPLETED",
            "ASSIGNED"
          ]
        },
        "dateTime": {
          "description": "The timestamp of the event occurrence in UTC",
          "type": "string"
        },
        "initiator": {
          "description": "The initiator of the event",
          "$ref": "#/definitions/initiator"
        }
      },
      "required": [
        "id",
        "type",
        "dateTime",
        "initiator"
      ]
    },
    "issue": {
      "description": "Details of the issue after the event occurred",
      "type": "object",
      "properties": {
        "key": {
          "description": "The JIRA issue key",
          "type": "string"
        },
        "summary": {
          "description": "The JIRA issue summary",
          "type": "string"
        },
        "body": {
          "description": "The JIRA issue body",
          "type": "string"
        },
        "status": {
          "description": "The JIRA issue status",
          "type": "string"
        },
        "priority": {
          "description": "The JIRA issue priority",
          "type": "string"
        },
        "initialAssignee": {
          "description": "The initial assignee of the issue before the escalation",
          "$ref": "#/definitions/jiraUser"
        },
        "fromAssignee": {
          "description": "The assignee of the issue before the event occurred",
          "$ref": "#/definitions/jiraUser"
        },
        "toAssignee": {
          "description": "The assignee of the issue after the event occurred",
          "$ref": "#/definitions/jiraUser"
        }
      },
      "required": [
        "key",
        "summary",
        "body",
        "status",
        "priority",
        "toAssignee"
      ]
    },
    "links": {
      "description": "Links to action the escalation",
      "type": "object",
      "properties": {
        "browse": {
          "description": "Url of the JIRA issue",
          "type": "string"
        },
        "escalate": {
          "description": "URL to escalate the issue",
          "type": "string"
        },
        "acknowledge": {
          "description": "URL to acknowledge the issue",
          "type": "string"
        },
        "complete": {
          "description": "URL to complete the issue",
          "type": "string"
        }
      }
    }
  },
  "definitions": {
    "initiator": {
      "description": "An initiator of an event",
      "type": "object",
      "properties": {
        "isBot": {
          "description": "True when Elevator for JIRA is running as a background process and triggering events. False for all user based initiations."
        },
        "user": {
          "$ref": "#/definitions/jiraUser"
        }
      },
      "required": [
        "isBot",
        "user"
      ]
    },
    "jiraUser": {
      "description": "A user in JIRA",
      "type": "object",
      "properties": {
        "id": {
          "description": "The JIRA ID of the user",
          "type": "integer"
        },
        "name": {
          "description": "The JIRA name of the user",
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    },
    "escalationState": {
      "description": "The state of an escalation",
      "type": "string",
      "enum": [
        "ESCALATED",
        "ACKNOWLEDGED",
        "COMPLETED",
        "ASSIGNED"
      ]
    },
    "elevatorRoster": {
      "description": "An Elevator for JIRA roster",
      "type": "object",
      "properties": {
        "id": {
          "description": "Unique identifier for the roster",
          "type": "integer"
        },
        "name": {
          "description": "The name of the roster",
          "type": "string"
        },
        "tier": {
          "description": "The 1 based index of the current tier in the roster",
          "type": "integer"
        }
      },
      "required": [
        "id",
        "name",
        "tier"
      ]
    }
  }
}

Sample Webhook Body

Example JSON body of Elevator Webhook

{
  "escalation": {
    "id": 1,
    "initiator": {
      "user": {
        "id": 10001,
        "name": "Administrator"
      },
      "isBot": false
    },
    "isReEscalated": false,
    "reEscalationInitiator": null,
    "fromState": null,
    "toState": "ESCALATED",
    "fromRoster": null,
    "toRoster": {
      "id": 1,
      "name": "Super team",
      "tier": 1
    }
  },
  "event": {
    "id": 1,
    "type": "ESCALATED",
    "dateTime": "2016-12-15T10:17:01.751Z",
    "initiator": {
      "user": {
        "id": 10001,
        "name": "Administrator"
      },
      "isBot": false
    }
  },
  "issue": {
    "key": "TEST-1",
    "summary": "Greetings from Elevator For Jira",
    "body": "Elevator for Jira is testing your webhooks",
    "status": "Open",
    "priority": "Major",
    "initialAssignee": {
      "id": 10100,
      "name": "Bob Bobson"
    },
    "fromAssignee": {
      "id": 10100,
      "name": "Bob Bobson"
    },
    "toAssignee": {
      "id": 10108,
      "name": "Terry Terryson"
    }
  },
  "links": {
    "browse": "http://jira.mycompany.com/browse/TEST-1",
    "escalate": "http://jira.mycompany.com/secure/ActionIssueEscalation.jspa?actionType=escalate&escalationEventId=1",
    "acknowledge": "http://jira.mycompany.com/secure/ActionIssueEscalation.jspa?actionType=acknowledge&escalationEventId=1",
    "complete": "http://jira.mycompany.com/secure/ActionIssueEscalation.jspa?actionType=complete&escalationEventId=1"
  }
}