Webhooks
Last updated
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.
1. To see the list of configured webhooks, go to the Administration configuration tab and choose the Webhooks menu item under WEBHOOKS.
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.
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:
|
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 |
Request header | This is a multiline text attribute that stores request headers in the following format:
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: |
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: 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:
|
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. |
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)
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 |
| The authentication token issued by the service provider. A string value. If used, it renders the webhook’s access token. |
| An object identifying the Email This Issue for Jira entity, to which the incident belongs. It can be the following:
The following attributes of the entity are accessible and can be used individually, too:
|
| 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. |
| Detailed, typically multiline text content. For example a stack trace of the exception. |
| 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. |
| The time when the incident occurred. |
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:
OpsGenie template
URL: https://api.opsgenie.com/v2/alerts
Headers: Authorization: GenieKey $!token
Request body:
Custom template
URL: <specify URL>
Header: Authorization: <specify authorization details>
Request body: <specify body>
Click the three dots next to a webhook item to access the following actions:
Test Webhook
Edit
Enable/disable
Delete
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.
Webhooks can be deleted manually. When deleted, all corresponding webhook execution log entries will be removed, too.
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.
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.