Alerting via Webhooks

Alerting allows Email This Issue for Jira administrators (and in some respects, regular users, too) to get some feedback in the form of notification alerts in the event of run-time failure or misconfiguration of incoming mail connections, outgoing mail connections and mail handlers.

Alerts and notifications may be sent for various incidents.

Incident types	Target audience for the alert	Feedback type
Manual emails not sent	Users who sent the emails	The outgoing email status is indicated: in the Audit Log (only visible for admins), on the Emails tab of the issue screen visible for any logged-in user).
Outgoing Mail Connections not working / Outgoing Emails end up in Error Queue Outgoing Emails end up in the Outgoing Error Queue. this may be caused either by errors at the infrastructure level (connection error) or by errors in the app, like templates that prevent the generation of emails	Administrators	Webhook alert
Incoming Mail Connections not working Emails cannot be downloaded	Administrators	Webhook alert
Mail Handlers fail to process emails Incoming emails end up in the Incoming Mail Error Queue	Administrators	Webhook alert
Mail Handlers filter out emails Incoming emails end up in the Incoming Mail Skipped Queue	Administrators	Webhook alert

Notification to end users

In Email This Issue for Jira, emails are queued and delivered in batch. In the past, if an email could not be delivered successfully, end-users had no feedback on the failure (except for the admin, who could check the Error Queue manually). Now, by displaying the status of the outgoing emails on the Emails tab of the Jira issue, regular users can also monitor the dispatch process and make sure if their message was sent in fact. If not, they can contact their Jira administrator to fix the issue and send the affected message(s) again via the Resend operation afterwards.

Status values include:

• QUEUED: if the audit log entry for an outgoing email is created. This status is available in the Server and DC versions.

• SUCCESSFUL: if the email was correctly sent via the corresponding Outgoing Connection

• FAILED: if the email could not be sent via the corresponding Outgoing Connection and resulted in the Error Queue

Notification to (system) administrators

The notification can take place in various forms and on different channels, however, technically speaking, they are all kind of HTTPS requests sent to a third-party service (some web - mostly REST - API calls), this is why the are called webhooks. Email This Issue provides you built-in integrations (i.e. pre-filled templates) with two popular service providers, by default:

• OpsGenie for advanced incident management

• Slack for prompt and instant visibility across the whole team.

Besides these two, the user may configure any other (custom) service of their choice.

The webhook alert may include several additional information about the source event (e.g. to help in the identification of the issue and creating a more particular ticket for the incident or to send a more customized, formatted message with sufficient details). These details can be referenced and inserted into a highly customizable, JSON-based template via pre-defined Velocity variables.

The administrator may create and configure various webhooks for a variety of incidents that will fire alerts individually, if their trigger criteria are met. Each webhook can be temporarily enabled or disabled. In addition, any newly created webhook can be tested with self-specified test data to double-check the structure and content of the resulting alert.

The administrator has the choice to suppress subsequent identical incidents, preventing the flooding/spamming of the channel used for alerting (without delivering any added value). By applying this setting, if the same type of issue prevails for a longer time (i.e. a series of events have the same root cause), the incident will only be fired after a one hour long time window again.

Each time an event is fired that is matching an active webhook configuration, the webhook is being executed, i.e. the notification alert is being constructed based on the specified template and then getting sent out. A particular event may fire multiple webhooks, so it is possible to send notifications about the same incident via different channels (e.g. both into OpsGenie and Slack at the same time).

Administrators are allowed to inspect the logs generated upon each webhook execution. If there is some issue with sending out the notifications, the administrator can double-check the configuration of the respective webhook and do the necessary fixes accordingly. Webhook executions logs are listed based on their time of execution, in descending order. In addition, they are automatically deleted after 90 days.

More information on configuring webhooks and on the interpretation of webhook execution logs can be found in the following pages, respectively:

pageWebhooks

pageWebhook execution logs