Webhooks

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) System Notifications (resulting in no entry in any Mail Log)
Service URL	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: https://serviceproviderurl/rest/alert/entity/$!entity.id 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. For more information, see: Slack Configuration to Receive Webhooks OpsGenie Configuration to Receive Webhooks
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: Read Timeout on Account1: A webhook is called. Read Timeout on Account1: A webhook is only called if this attribute is True. FolderClosedException on Account1: A webhook is called because the error is different. FolderClosedException on Account2: A webhook is called because the account is different.
Status	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. 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
$!token	The authentication token issued by the service provider. A string value. If used, it renders the webhook’s access token.
$!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

URL: https://slack.com/api/chat.postMessage

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

URL: https://api.opsgenie.com/v2/alerts

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

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 Slack Configuration to Receive Webhooks and OpsGenie Configuration to Receive Webhooks. In case of Custom webhooks, see the documentation of the external receiving system to learn how to connect them to trusted applications.