JIRA Service Desk webhooks

When you create an automation rule, you can use a webhook THEN action to send JIRA Service Desk events to third-party applications and add-ons. For example, you might use a webhook to alert your remote application when an SLA is about to be breached. When you use a webhook, your remote application doesn't have to periodically poll JIRA Service Desk to find out if changes have occurred.

A webhook is a user-defined callback over HTTP. In JIRA Service Desk, webhook configuration is built into the automation settings. This page describes how a webhook works and shows you how to configure one.

The JIRA Service Desk webhooks feature is available in JIRA Cloud and JIRA Server (3.2 or later).

On this page:

Overview

A JIRA Service Desk webhook is a THEN action in an automation rule. When you configure a rule, you can specify WHENs and IFs, then use the webhook to define your action. For example, this image shows a rule that uses a webhook to page second-level support when a "Time to Resolution" SLA is about to breach:
 

Adding a webhook to an automation rule

  1. Navigate to Project settings Automation, then create a Custom  rule or edit an existing rule.
  2. Configure the WHEN and IF settings as desired, then add a THEN action and choose Webhook.
  3. Configure the webhook settings, name your rule, and save it.

Webhook settings

  • URL — In JIRA Service Desk Cloud, use port 80 for "http://" URLs and port 443 for "https://" URLs.
  • JIRA issue payload — If you choose the Send JIRA issue payload in request body option, a JSON object containing the issue details is attached to the request body. The shape of the JSON payload is as follows:

      Show me...
    {
        "issue" : {
            "id": "18001",
            "self": "https://mycompany.atlassian.net/rest/api/2/issue/18001",
            "key": "IT-4",
            "fields": {
                "summary" : "I cannot get my second screen to work",
                "description" : "Have tried multiple ports, cables, but no luck",
                "status" : {
                    "name" : "Waiting for Support",
                    ...
                },
                "reporter" : {
                    "name" : "jsmith",
                    ...
                },
                ...
            }
        },
        "timestamp" : 1462941258113 // Time when webhook was fired - UTC milliseconds from epoch
    }

    For more information about issue shape, see JIRA REST API get-issue endpoint. Note that expand params are not applicable to JIRA Service Desk Webhook.

    Issue information in the payload is generated by the user who runs the automation rule. This user can be configured as the Project Default or the user who triggers the rule. If the user does not have permission to see some fields, then those values do not render. See Automating Your Service Desk for more info.

Webhook execution

  • Request method — When a webhook THEN action triggers, JIRA fires an HTTP POST request to the URL you configured.
  • Success criteria and timeout — A webhook HTTP POST request is considered successful if the server returns a response with status code range 200 (inclusive) to 300 (exclusive). JIRA Service Desk waits 5 seconds to establish a TCP connection with the webhook server, and 20 seconds for a response after connection is established. If the webhook requests fails, JIRA Service Desk does not retry the connection.
  • Asynchronous webhook execution — The webhook THEN action is executed asynchronously. If many executions are triggered in a short period of time, they are queued and actioned one at a time without blocking the other automation rules you have in JIRA Service Desk.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport