Jira¶
Jira notification targets send TrueWatch alerts in JSON format to Jira intake workflows through a webhook (an HTTP endpoint that receives external notifications). You can configure field mappings and processing actions in Jira to route alerts to project teams for handling.
This article uses the Incoming webhook in Jira Cloud Automation as an example. The project and issue type to which an issue belongs, the creation or update rules, deduplication, and status maintenance are all controlled by Jira automation rules.
Configure intake rules in Jira¶
You need edit permission for automation rules in the target project.
- Go to Automation in the target Jira project and create an automation rule.
- Add an Incoming webhook trigger.
- Add a processing action such as Create issue, and select the project and issue type. For the initial connectivity test, you can use a fixed summary, for example, "Monitoring notification test"; after confirming receipt, map the summary to
{{webhookData.title}}and the description to{{webhookData.message}}based on actual alerts. - Select Save flow without enabling, enter a rule name, and save.
- Reopen the Incoming webhook trigger, select No issues from the webhook, and copy the Webhook URL and Secret. Save the trigger configuration and enable the rule.
Jira uses webhookData to read JSON fields in the request. An alert notification can contain multiple events. Depending on your business needs, create one issue for the entire notification or iterate over events to process each event separately, and map event context, backlinks, and monitor links in monitor_checker_links to issue fields.
For the configuration of the intake endpoint and Secret, see the Jira Incoming webhook official documentation; for field mapping, see the official Jira alert integration example.
Create a notification target in TrueWatch¶
Go to Monitoring > Notification Targets > Create Notification Target and select Jira.
- Enter a name to identify the notification target in lists and alert policies. The name must be unique within the current workspace and can contain up to 200 characters.
- In Webhook URL, enter the complete HTTPS URL provided by Jira, using the final address that actually receives POST requests.
- For Authentication Method, select Secret, and enter the Secret generated by Jira. The system sends this value through the
X-Automation-Webhook-Tokenrequest header. - Configure other authentication methods and custom request headers as required by the receiving end.
- Click Send Test Notification, preview and confirm sending. The test actually invokes the Jira rule, and subsequent actions are executed according to the rule.
- Go to Audit log in Jira, confirm that the rule execution record for this test appears, and verify the alert fields and issue processing results.
- Configure operation permissions, and confirm and save.
- In the alert policy, select this notification target and configure the event severity levels and scopes to send.
Other authentication methods and custom request headers¶
The native Incoming webhook in Jira Cloud Automation uses Secret. When integrating with a gateway, plugin, or self-hosted receiving service, select the authentication method according to the protocol actually supported by that endpoint.
| Authentication Method | Value | Usage Notes |
|---|---|---|
| Secret | Secret | Applicable to the Jira Cloud Automation endpoint above. |
| Basic | Username, password | Provide credentials as agreed with the receiving end; the username must be non-empty and must not contain colons. |
| Bearer Token | Token | Enter the original value of an existing Access Token; the system adds the Bearer prefix. Update it after the token expires or is revoked. |
| API Key | Header name, API Key | Enter the header name and complete value as agreed with the receiving end; Content-Type is a reserved name. |
| No authentication | — | Configure custom request headers as required by the receiving end. |
Enable Custom Request Headers as needed, and add the keys and values required by the receiving end. Header names are deduplicated case-insensitively; headers generated by the selected authentication method take precedence over custom headers with the same name. Content-Type is fixed to application/json, and Accept defaults to application/json.
Edit credentials¶
When editing a saved target, under the same address, authentication method, and identity, leave Secret, password, Token, or API Key blank to retain the original value, or enter a new value to replace it. After changing the address, authentication method, username, or API Key header name, you need to enter the corresponding credentials.
Custom request header values are stored encrypted. When the above configurations remain unchanged, you can leave the value of a saved header with the same name blank to retain it, or enter a new value to replace it; deleting the row removes the header. After adding or renaming a request header, or changing the above configurations, enter the complete header value.
Tests use the valid configuration currently in the form; after saving, subsequent alerts use the new configuration. After regenerating the Jira Secret, update the Secret in the notification target accordingly.
Notification content and alert aggregation¶
Jira notification targets use the alert aggregation format of Simple HTTP Request and support normal, rule-based aggregation, and intelligent aggregation notifications. The receiving end parses alerts using the following fields:
| Field | Description |
|---|---|
title, message, status |
Title, body, and status of the current notification. |
events |
Event list. A normal alert contains one event; an aggregated alert contains the corresponding group of events, retaining event context and backlinks. |
workspace_uuid, workspace_name |
ID and name of the workspace to which the event belongs. |
monitor_checker_links |
Monitor names and event list links in rule-based aggregation and intelligent aggregation notifications. |
The alert policy determines which events are grouped into the same notification; sending starts after the notification content is constructed. Notifications configured with an explicit delay are still sent at the specified time.
Testing and troubleshooting¶
The fields in a test notification are based on the JSON actually received by the receiving end. After completing the endpoint and authentication tests, use actual normal and aggregated alerts to verify the mapping of fields such as title and events; using a fixed summary for the first test prevents issue creation from failing when the test sample lacks title.
An HTTP 2xx response from the intake endpoint only indicates that the request is complete. The new Jira Incoming webhook may also return HTTP 200 when the Secret is incorrect or the rule does not exist. Use the execution record for this test in the Audit log, field parsing, and subsequent action results to determine whether the integration is successful.
| Symptom | Check |
|---|---|
| The request completes, but there is no record for this test in the Audit log | Check that the rule is enabled and that the URL and Secret come from the same trigger; after regenerating the Secret, update the notification target accordingly. |
| The rule executes, but issue fields are empty | Check the webhookData field paths, and verify parsing separately with actual normal and aggregated alerts. |
| The number of issues differs from expectations | Check whether the rule executes for the entire notification or for events in events, as well as the deduplication rules on the Jira side. |
| Sending fails | Check the final HTTPS address, certificate, network connectivity, and receiving end permissions. HTTP 3xx redirects are treated as send failures. |
For more troubleshooting methods, see the Jira Incoming webhook official testing guide.