Email This Issue
📈 Marketplace❓ Support❤️ Feedback🏠 META-INF Apps
Email This Issue - for Jira Server/Data Center
Email This Issue - for Jira Server/Data Center
  • ⬇️Start Here
  • Email This Issue - for Jira Server/DC
  • Features
  • Secure the email channel with Email This Issue
  • Comparing Email This Issue and Jira Server/DC
  • 🤓Documentation
    • Outgoing Emails
      • Sending manual emails
        • The difference between email editors
        • Enabling template categories so templates can be chosen on the Email screen
        • Mail Generation Queue (formerly called Event Queue)
        • Manual Email Default Settings
      • Sending issue filters by email
      • Email templates
        • Adding custom macro to email templates
        • Adding Email Audit Log to email templates
        • Adding fields to email templates
        • Adding issue comments to emails
        • Adding issue link information to your template
        • Adding issue operation links to the email
        • Adding a signature with a company logo to emails
        • Adding user properties to emails
        • Disabling links and avatars or icons in templates
        • Formatting Date and Time values
        • Using reply templates
        • Using Mail Body Initializer templates
        • Rendering templates within templates
        • Velocity Context in email templates
        • Formatting number values
        • Searching for issues in email templates
        • Changelog information in email templates
        • Canned responses
      • Contexts
        • Context Resolution Algorithm
      • Event Notifications
      • Distribution lists
      • Workflow post functions
      • Custom fields
    • Incoming Emails
      • Attachment Filtering
      • Next Generation Mail Handlers
        • Jira automation and Next Generation Mail Handlers
        • Using regular expressions
      • Classic Mail Handlers - Deprecated
        • Mail Handler Error Log
        • Step-by-step Classic Mail Handler to Next Generation Mail Handler migration aid
        • Field Rules
        • Phasing out the Classic Mail Handler
        • Comparing the Classic and the Next Generation Mail Handlers
    • Integrations
      • CRM for Jira
      • nFeed
      • Glass Documentation
      • API - Integration with other services
    • Administration
      • General configuration
      • Email Audit Log
      • Outgoing Mail Connections
      • Outgoing Mail Queue
      • Incoming Mail Connections
      • Incoming Mail Queue
      • Incoming Mail Log
      • Backup and restore settings
        • Backup and restore administration
          • Backup menu
          • Restore menu
        • Backup and Restore Tutorials
          • Backup and restore for empty email settings
          • Backup and restore only parts of a configuration
          • Backup and restore every setting in the same instance
      • OAuth2 Authorizations in Email This Issue
        • OAuth2 Client Credentials
        • Authorizing Email This Issue to access Gmail accounts
        • Authorizing Email This Issue to access Microsoft 365 accounts
        • Enabling OAuth2 Authorization in your Google Account
        • Enabling OAuth2 authorization in your Microsoft 365 account
        • Troubleshooting guides for Microsoft OAuth2 Connections
          • How to fix "Authorization Was Interrupted" error
          • How to fix "BAD User is authenticated but not connected" error
          • How to fix "401 Unauthorized" error
          • How to fix "key expires_in " error
          • How to fix "Need admin approval" error
      • Alerting via Webhooks
        • Webhooks
          • Configuring Slack to receive webhooks
          • Configuring OpsGenie to receive webhooks
        • Webhook execution logs
      • Email Security
    • Service management integration
    • JQL Functions
    • Top-level menu navigation
  • ☁️Server to Cloud Migration
    • Server to Cloud - Automatic Migration tool
    • Server to Cloud - Manual migration guide for Email This Issue
      • Overview of available features
      • Differences of the Server and Cloud user interface
      • Migrating Outgoing Settings
        • Migrating Templates
        • Migrating Notifications
        • Migrating Manual Email Defaults
        • Migrating Contexts
        • Migrating Canned Responses
        • Migrating Post Functions
        • Migrating Outgoing Mail Connections
      • Migrating Incoming Settings
        • Migrating Classic Mail Handlers
        • Migrating Next Generation Mail Handlers
        • Migrating Incoming Mail Connections
        • Migrating Incoming Mail Queue Settings
        • Migrating Incoming Mail Log Settings
      • Migrating Other Settings
        • Migrating OAuth2 Credentials
        • Migrating global default email settings
        • Migrating permissions for sending emails manually
        • Migrating recipient restrictions
  • ❓FAQ
    • FAQ
      • How to bypass workflow conditions
      • How to avoid email loops
      • How to control who to send emails to
      • How to customize Email From in outgoing emails
      • How to enable logging
      • How to install license keys
      • How to find out why the Email button is missing
      • How to obtain a community or non-profit license
      • How to prevent duplicate emails
      • How to remove old content from reply emails
      • How to send personalized emails to recipients
      • How to set up auto-reply or acknowledgment emails
      • How to track cases when you don't get any emails
      • How to view the log of incoming and outgoing emails
      • The iOS Mail app does not show attachments
      • How to route emails to projects
      • How to maintain email threads in Jira
      • How to fix issues with a corrupt index state
      • How to set polling interval for mail accounts manually
    • Tutorials
      • Configuring email approval
      • Customizing the email template used with manual emails
      • Enhance Jira Service Management with Email This Issue
      • Getting Started
      • Setting up an Email Help Desk
      • Setting up customized notifications
      • Setting up a Service Management with a Next-Gen Mail Handler
  • 🌪️Misc
    • Open Source Components
    • Pricing Updates
      • Pricing Update effective October 1st 2018
      • Pricing Update effective December 1, 2021
    • End of Support Policy
    • Security Advisories
      • Email This Issue Security Advisory 2020-02-18
    • Database Tables
    • Translations
  • 🆕Release Notes
    • Release notes
      • 9.x.x
        • 9.15.0 Jira 10 compatibility
        • 9.13.0 Improvements and Fixes
        • 9.11.0 Improvements and fixes
        • 9.10.0 Major improvements and fixes
        • 9.9.1 Improvements and fixes
        • 9.9.0.2 Major improvements and fixes
        • 9.8.0 Improvements and fixes
        • 9.7.0 Improvements and fixes
        • 9.6.0 Improvements and fixes
        • 9.5.0 Improvements and fixes
        • 9.4.0 Bugfixes
        • 9.3.3. Improvements and fixes
        • 9.3.2 Major improvements
        • 9.3.1 Automatic cloud migration
        • 9.2.2.1 Bugfixes
        • 9.2.2 Improvements and fixes
        • 9.2.1.3 Compatibility changes for Jira 9.0.0
        • 9.2.1 Major improvements
        • 9.2.0 Improvements and fixes
        • 9.1.1 Improvements and fixes
        • 9.1.0.1 Alerting and other major new features
        • 9.0.2 Bugfixes, next step in deprecating the Classic Mail Handler
        • 9.0.1 Minor improvement and fixes
        • 9.0.0 Major improvements
        • 9.12.0 Improvement and fixes
        • 9.17 Improvements and Fixes
        • 9.18.0 Improvements and fixes
      • 8.1.x
        • 8.1.3 Classic handler is deprecated, timezone support, bug fixes
        • 8.1.2 Important bug fixes
        • 8.1.1 Microsoft 365 OAuth2, improvements and fixes
        • 8.1.0 Microsoft 365 OAuth2, improvements and fixes
      • Up to 8.0.6
Powered by GitBook
On this page
  • Listing webhooks
  • Adding a new webhook
  • Webhook attributes
  • Webhook variables
  • Webhook templates
  • Slack (Web API method) template
  • OpsGenie template
  • Custom template
  • Additional webhook actions
  • Testing a webhook
  • Deleting webhooks
  • Setting up service providers

Was this helpful?

  1. Documentation
  2. Administration
  3. Alerting via Webhooks

Webhooks

PreviousAlerting via WebhooksNextConfiguring Slack to receive webhooks

Last updated 5 months ago

Was this helpful?

Webhooks allow admins to send incident alerts to various systems capable of receiving HTTP(S) POST messages and handling them appropriately. These systems provide more sophisticated ways to process alert messages, as they can do escalation, and send text messages or other types of notifications, such as OpsGenie and Slack.

Webhooks can be configured for various incident types. Webhook requests include he following:

  • HTTP(S) request headers for authentication . Typically, this is token-based.

  • Additional headers

  • A request body containing a JSON object structure matching the requirements of the receiving service.

Note: The request body includes placeholder values that render dynamic data, such as error messages, into the relevant part of the JSON structure. Such a templated request body helps to adapt the request format to that of the receiving system (OpsGenie, Slack, etc).

Email This Issue for Jira has OpsGenie and Slack integration. Use pre-filled request headers and JSON body templates, customize them on the Webhook configuration UI, or create custom Webhooks to accommodate the needs of other systems, too.

Listing webhooks

To see the list of configured webhooks, go to WEBHOOKS --> Webhooks.

Adding a new webhook

To create a new webhook do the following:

1. Go to the Webhooks menu item under WEBHOOKS.

2. Click on the Add button on the upper right corner of the page and choose the service provider from the dropdown list to load the pre-filled template.

Note: Before saving webhooks are checked for basic syntax errors, for example an invalid URL pattern. However we advise for users to test the webhook.

Webhook attributes

Attribute
Description

Name

Name of the webhook

Description

Longer description of this webhook

Event

Webhook events that trigger webhook notifications, one of the following:

  • Incoming Mail Connection Incident (also resulting in an entry with FAILED status in the Incoming Mail Log)

  • Outgoing Mail Connection Incident (also resulting in an entry with FAILED status in the Outgoing Mail Log)

  • Mail Handler Mail Filtered Out (resulting in an entry with SKIPPED status in the Incoming Mail Log)

  • Mail Handler Mail Processing Failed (resulting in an entry with FAILED status in the Incoming Mail Log)

Service URL

HTTPs URL to call the service. This is an URL template, which may contain variable placeholders to render the final URL dynamically.

The Service URL can always be edited in all webhook types, but it is pre-filled for the supported service providers (Slack, OpsGenie).

API Token

This is an app/API token that is used to authenticate Email This Issue for Jira by the service provider. Usually, this is an OpsGenie API Key, or a Slack Bot User OAuth Token, or something similar.

This attribute is stored in an encrypted format just like passwords.

Note: Currently, this token must be obtained manually in advance and provided by the administrator in the configuration UI.

Request Header

This is a multiline text attribute that stores request headers in the format indicated below. The listed headers are added to the HTTPs request.

The Request Header can always be edited in all webhook types, but is pre-filled for the supported service providers (Slack, OpsGenie).

Request Header is practically a Velocity Template which may include variables to render dynamic data in header values, and admins can add arbitrary headers to the request.

For example: "alias=mailhandler-$!entity.id" Request Header typically includes the API token in a format the service provider requires. The API Token may be added to a header using the variable $!token, see details below.

Request Body

This is a multiline text attribute that defines the request body typically in JSON format.

For the time being, the JSON format is supported only.

The Request Body can always be edited in all webhook types, but is pre-filled for the supported service providers (Slack, OpsGenie).

Request body is practically a Velocity template which may include variables to render dynamic data in values, and admins can add custom content to the request.

For example:

Note: In case of Slack, the request body has a placeholder for the channel ID (see <channel id>), which cannot be pre-filled automatically. Here, the placeholder shall be replaced by the actual channel ID (where the messages shall be posted to) to get the webhook work.

Enable Subsequent Identical Incidents

True/False toggle, default is False. If set to True, the webhook is called each time an event is fired, even if the same errors occur on the same entities. If set to False, the webhook is called once in a series per error type and entity (i.e. the events of the same type are suppressed).

For now, the suppression time window is set to an hour. This cannot be changed.

For a more precise interpretation, do not suppress triggering events, but the calling of the associated and enabled webhook. As a consequence, the same event can result in a notification for a webhook while being suppressed for another webhook, even if it is fired several times within an hour.

For example, the following series of events is a possible scenario:

  1. Read Timeout on Account1: A webhook is called.

  2. Read Timeout on Account1: A webhook is only called if this attribute is True.

  3. FolderClosedException on Account1: A webhook is called because the error is different.

  4. FolderClosedException on Account2: A webhook is called because the account is different.

Status

Important: Do not confuse a webhook in a Success state with the root cause of the event being fired or suppressed. This status indicates the result of the last call to the external service, for example when the notification about a failure should have been sent, but the dispatch of the request failed.

Note: The failure of a webhook can be caused by a general network error or a misconfigured webhook. In the latter case, the administrator is recommended to test the webhook using dummy data in the Action menu.

Enabled

True/False toggle, default is true, only enabled webhooks are called.

Last Execution

The timestamp of the last execution.

Webhook variables

Webhooks use Apache Velocity to render headers/body content dynamically. The following variables are available and may be used in request headers and body:

Variable
Description

$!entity

An object identifying the Email This Issue for Jira entity, to which the incident belongs. It can be the following:

  • an incoming connection

  • an outgoing connection

  • a mail handler

The following attributes of the entity are accessible and can be used individually, too:

  • ID

  • Name

  • Type: The type of the entity (enumerated type, values are OUTGOING_CONNECTION, INCOMING_CONNECTION, MAIL_HANDLER)

  • Link: The link to the entity listing page in the app with ID of the entity. This URL is composed of the Jira instance URL and the relative navigation parts.

$!message

A single line text message, this is the main message and can be an error message, filter name, etc. depending on the event type of the associated webhook.

$!details

Detailed, typically multiline text content. For example a stack trace of the exception.

$!jiraBaseUrl

The base/instance URL of the Jira instance where the incident occurred. It helps to identify the Jira instance if there are multiple instances being monitored.

$!timestamp

The time when the incident occurred.

Webhook templates

Email This Issue for Jira provides basic Slack and OpsGenie integration. For these service providers the templated configuration fields are pre-filled. These templates result in well-formatted messages and requests that suit most typical use cases.

Note: Templates can be adjusted and/or extended even with pre-filled Slack and OpsGenie templates, provided that the resulting template has a valid JSON syntax. In case of custom service providers, administrators should consult the documentation of the chosen service to construct the appropriate structure and content of the request.

The content of the pre-filled templates is the following:

Slack (Web API method) template

Header: Authorization: Bearer $!token

Request body:

{
    "channel": "<channel id>",
    "blocks": [
        {
            "type": "header",
            "text": {
                "type": "plain_text",
                "text": "Incident",
                "emoji": false
            }
        },
        {
            "type": "divider"
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": "The $!entity.type Entity *$!entity.name* ($!entity.id) encountered an issue"
            },
            "accessory": {
                "type": "button",
                "text": {
                    "type": "plain_text",
                    "text": "Inspect entity",
                    "emoji": true
                },
                "value": "inspect_entity",
                "url": "$!entity.link",
                "action_id": "button-action"
            }
        },
        {
            "type": "context",
            "elements": [
                {
                    "type": "mrkdwn",
                    "text": "*Error:* $!message"
                }
            ]
        }
    ],
    "attachments": [
        {
            "text": "*Error Details:* $!details"
        }
    ]
}

OpsGenie template

Headers: Authorization: GenieKey $!token

Request body:

{
    "message": "$!message",
    "alias": "$!entity.type - $!entity.id",
    "description": "$!details",
    "tags": [
        "Critical"
    ],
    "details": {
        "Entity Name": "$!entity.name",
        "Entity Type": "$!entity.type",
        "Entity ID": "$!entity.id",
        "Entity Link": "$!entity.link",
        "Jira Base Url": "$!jiraBaseUrl",
        "Incident Timestamp": "$!timestamp"
    },
    "entity": "Email This Issue",
    "priority": "P1"
}

Custom template

URL: <specify URL>

Header: Authorization: <specify authorization details>

Request body: <specify body>

Additional webhook actions

Click the three dots next to a webhook item to access the following actions:

  • Test Webhook

  • Edit

  • Enable/disable

  • Delete

Testing a webhook

To make sure a webhook works as expected, test notifications can be sent to the configured service providers. In this case, the firing of an event is simulated, as if the event for which the webhook is configured had been triggered. The details of the simulated incident (i.e. the source of the error) can be custom-tailored, for example dummy data for the message and entity variables can be specified.

Deleting webhooks

Webhooks can be deleted manually. When deleted, all corresponding webhook execution log entries will be removed, too.

Setting up service providers

E.g.

For more information, see:

Success: indicated by a green checkmark if the webhook works.

Failed: indicated by a red exclamation mark if the last call of the webhook resulted in an error.

URL:

URL:

In order to connect to external receiving systems, these systems might need to be pre-configured to work with the Email This Issue for Jira application. This can include registering or authorizing them, for example. The exact steps of preparation can be found in and . In case of Custom webhooks, see the documentation of the external receiving system to learn how to connect them to trusted applications.

🤓
headername=headervalue
headername=headervalue
...
{"message":"$!message", "details":"$!details","payload":"$!entity.name"}
https://slack.com/api/chat.postMessage
https://api.opsgenie.com/v2/alerts
Slack Configuration to Receive Webhooks
OpsGenie Configuration to Receive Webhooks
https://serviceproviderurl/rest/alert/entity/$!entity.id
Configuring Slack to receive webhooks
Configuring OpsGenie to receive webhooks