Email This Issue
📈 Marketplace❓ Support❤️ Feedback🏠 META-INF Apps
Email This Issue - for Jira Cloud
Email This Issue - for Jira Cloud
  • ⬇️Overview
  • Email This Issue - for Jira Cloud
  • Features
  • How Email This Issue Works
  • Secure the email channel with Email This Issue
  • Comparing Email This Issue and Jira Cloud
  • 📤Outgoing Emails
    • Outgoing emails overview
    • Manual emails
      • Configuring manual emails
      • Sending manual emails
    • Email notification schemes and email notifications
    • Workflow post functions
    • Advanced email configuration
    • Customizing email templates
    • Canned Responses (default messages)
    • Scope evaluation
  • 📥Incoming Emails (Mail Handlers)
    • Incoming emails overview
  • Mail handlers - adding / editing
    • General handler settings
    • Filtering
    • Finding issues
    • Setting up rules and actions in the actions editor
      • Adding/editing actions
      • Adding recipients to Request Participants
      • Creating an issue
      • Updating an issue
      • Setting field values
      • Adding comments
      • Sending auto-reply emails
      • Executing workflow transitions
      • Creating a customer
      • Using split regexp
      • Conditions
      • Approve request
      • Decline request
    • Maintaining email chains
    • Mail Handler New UI
  • Global Sender Address Filters
  • Attachment Filters
    • Regular Attachment Handling Deprecation
  • 🤓Administration
    • Outgoing Mail Connections
    • Alerting via Webhooks
      • Webhooks
        • Configuring Slack to receive alerts via webhooks
        • Configuring OpsGenie to Receive alerts via webhooks
        • Configuring Microsoft Teams to receive alerts via webhooks
      • Webhook execution logs
    • Mail Queue
    • Email Audit Log
    • Permissions
    • Recipient Restrictions
    • Incoming Mail Connections
    • Email Security
    • Incoming Mail Queue
    • Incoming Mail Log
    • OAuth2 Credentials
      • Enabling OAuth2 Authorization in your Google Account
      • Enabling OAuth2 Authorization in your Microsoft 365 Account
      • Troubleshooting guides for Microsoft OAuth2 Connections
        • 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
  • ☁️Server to Cloud Migration
    • 🛫Server to Cloud - Automatic Migration tool
      • Preparing for the migration
      • Doing the migration
      • Finalizing the migration in Cloud
      • Migration with unsupported Jira versions causes errors
    • Server to Cloud - Manual migration guide for Email This Issue
  • ❓FAQ
    • No recipients error in outgoing emails
    • How-to add custom macro to email Template?
    • Why cannot I select custom event types in notification?
    • How to configure the Email This Issue addon user in Jira Cloud?
    • I get an error: Could not create request on behalf of the sender
    • Why is the Incoming Mail Queue size limited?
    • Outgoing mail not sent - Read timeout error
    • Access restriction icon is not appearing when adding internal attachments via Email this Issue
  • 🌪️General
    • Release Notes
    • API
      • API for Velocity Context Objects - 1.7
      • API for Velocity Context Objects
    • Addon Pages
      • Integrity Check
      • Feedback and Support
    • Security Advisories
      • Email This Issue Security Advisory September 28, 2020
    • Appendix
      • Supported Time Zones
    • Integration of Glass Documentation
Powered by GitBook
On this page
  • Listing webhooks
  • Adding a new webhook
  • Webhook attributes
  • Webhook variables
  • Webhook templates
  • Additional webhook actions
  • Testing a webhook
  • Deleting webhooks
  • Setting up service providers

Was this helpful?

  1. Administration
  2. Alerting via Webhooks

Webhooks

PreviousAlerting via WebhooksNextConfiguring Slack to receive alerts via 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

1. To see the list of configured webhooks, go to the Administration configuration tab and choose the Webhooks menu item under WEBHOOKS.

Adding a new webhook

To create a new webhook do the following:

1. Go to the Administration configuration tab and choose 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

The name of the webhook

Description

A longer description of this webhook

Event

Webhook events triggering webhook notifications. Can be the following:

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

  • Outgoing Mail Connection Incident (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

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

API token

This is an app/API token that is used for authenticating Email This Issue for Jira by the service provider. Usually, this is an OpsGenie API Key, 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 following format:

1 headername=headervalue

2 headername=headervalue

3 ...

The listed headers are added to the HTTPs request.

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

Note: The Request Header is a Velocity Template that can include variables to render dynamic data in header values, and admins can add arbitrary headers to the request. For example: “alias=mailhandler-$!entity.id” The request header typically includes the API token in the format required by the service provider. 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.

Note: For the time being, only the JSON format is supported. The request body can always be edited in all types of webhooks, but it is pre-filled for the supported service providers (OpsGenie, Slack).

Request body is a Velocity template that can include variables to render dynamic data in values, and admins can add custom content to the request. For example: {"message":"$!message", "details":"$!details","payload":"$!entity.name"}

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

Enable Subsequent Identical Incidents

On the True/False toggle the 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

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.

System Notifications

These alerts will notify you if your site is affected by any performance issues or quality maintaining countermeasures (e.g. rate limiting after an abruptly large amount of email traffic)

Webhook variables

Webhooks use Apache Velocity to dynamically render headers and body content. The following variables are available and can 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

(resulting in no entry in any Mail Log)

The HTTPs URL to call the service. This is an URL template, that can contain variable placeholders to render the final URL dynamically. For example:

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. 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.

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.

🤓
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
Slack Configuration to Receive Webhooks
OpsGenie Configuration to Receive Webhooks
System Notifications
:warning:
:check_mark: