Alert Relay setup guide

Alert Relay for Jira Service Management is being prepared for Marketplace review. This guide describes the intended setup after the app is available. It does not contain a live endpoint, webhook URL, or token.

Before you start

• The direct Jira Service Management Operations Webhook integration requires a JSM Premium or Enterprise plan.
• Alert Relay needs an active Marketplace license to configure, test, and deliver alerts.
• You need Jira administrator access and a Google Chat space where incoming webhooks are allowed.
• Choose a Chat space whose membership is approved to see the alert fields that you enable.

1. Connect a Google Chat space

1. Open Alert Relay in Jira administration.
2. Enter a connection name and the incoming webhook URL for the approved Google Chat space.
3. Use Test Chat webhook to send the app's fixed synthetic test card.
4. Confirm the Chat audience and save the connection.
5. Copy the Forge endpoint and the one-time JSM webhook token shown by the app. Store them in your organization's approved secret manager. Do not put either value in tickets, source control, screenshots, or logs.

2. Create a JSM Operations Webhook integration

1. In Jira Service Management Operations, open the integration settings and add a Webhook integration.
2. Choose Authenticate with a Webhook account.
3. Paste the Forge endpoint into the JSM webhook URL field.
4. Add the custom HTTP header X-Chat-Relay-Token with the token from Alert Relay.
5. Keep Add alert description to payload and Add alert details to payload disabled. The app does not need these fields.
6. Save and turn on the integration.

3. Map alert actions

For each action you want to send to Chat, select Post to Webhook URL in the JSM alert-action mapping. Start with the actions your on-call team needs and add others deliberately. Optional note or message text is ignored by Alert Relay, but the corresponding JSM request may still contain it before the app filters the payload.

4. Set the delivery policy

Select the connection whose policy you want to inspect. Set the minimum priority for immediate messages and the digest interval (5–1440 minutes). Lower-priority events are grouped for the next due digest. The policy is per connection.

5. Verify delivery

Send one synthetic alert through the configured action mapping. Check the Chat card and thread, then compare the app's bounded journal with the message in Chat. An HTTP 202 Accepted response confirms endpoint acceptance only; it does not confirm that Chat received the message. Verify an exact replay separately because delivery and Forge storage cannot be committed atomically, so an ambiguous network result may lead to a repeat.

Optional Automation fallback

An administrator may configure a Jira Automation web request where the site's plan and available trigger provide the needed alert fields. That path is separate from the native Operations Webhook and may not expose every Operations action or responder change. Check the Automation audit log before relying on a trigger for a specific event.

Data minimization and troubleshooting

The direct Operations path uses the action, alert ID, update timestamp, and recognized priority; escalation events can use the documented escalation time and repeat count when the update timestamp is absent. Descriptions, notes, message text, usernames, user IDs, teams, recipients, and other fields are not included in the app's alert record or Chat card. Automation can include owner or responder display names and an alert link.

Pause or remove a connection if its destination is no longer approved. If an endpoint or token may have been exposed, rotate the token in Alert Relay and replace the header in JSM. Contact Alert Relay Support with a redacted description; never send the webhook URL, token, or customer alert payload.