Set up a space, then a route.

Install

1. Install ChatHerald from the Atlassian Marketplace on your Jira Cloud site. The Marketplace listing is coming soon.
2. Install the same app on Confluence if you want page notifications. Jira and Confluence are separate installs.
3. Open Jira administration and choose the page titled ChatHerald.
4. Paste a webhook, use Send test, then add a rule. Send test does not read a Jira issue. The message says so.

A development or staging install has no context.license value, so editing stays open. After a paid install, an inactive licence keeps the rules and locks editing. Delivery stops until the licence is active again.

Pricing and free trial are shown on the Atlassian Marketplace listing (coming soon).

Uninstall

ChatHerald has no uninstall step of its own. When an admin uninstalls the app, Atlassian deletes the app’s Forge storage for that site (rules, webhook URLs, queues, and the delivery log) under Atlassian’s data retention policy. Details are in the privacy policy.

Create a Google Chat webhook

1. In the Google Chat space, add an incoming webhook. Google documents this under the space’s apps and integrations.
2. Copy the webhook URL. ChatHerald accepts only https://chat.googleapis.com/v1/spaces/SPACE/messages with both key and token query parameters.
3. In ChatHerald, paste the URL and save it. Give it a label if you have more than one space.
4. Choose Send test. A successful test posts “ChatHerald test” and records a delivery-log row with issue key TEST.

The screen shows a masked URL. The full URL, including the token, is stored in the app’s Forge storage as a secret. Other hosts, plain http, a missing key or token, and a username or password in the URL are rejected.

The default message is text, with the key fields and a deep link. You can switch a site to text plus a rich card. Keep text on until a real space shows the card the way you want. Google’s incoming-webhook guide documents a text body.

Add a route with JQL

Save a webhook before you add a rule. You can start from a template or write a custom rule.

Templates included now:

• High-priority bugs moving to In Review
• Blockers created
• Comments on a project
• Mentions
• Confluence page created or updated
• Daily digest of new issues

Coming soon: the template “JSM SLA warning”. It appears in the list but cannot be added yet. Forge has no SLA-breach event, and the scheduled SLA check is not built.

A rule can require any combination of:

• Event: issue created, status transition, other field change, comment, mention, page created, page updated.
• Project, issue type, priority, and label. Labels match if the issue has any label you listed.
• For a status transition, the destination status, and optionally the status it left. Names come from the issue changelog, so “In Review” must match the workflow name.
• JQL. Jira checks the query when you save the rule. When an event arrives, the app asks Jira whether that one issue matches. ORDER BY is ignored for that check. JQL is not applied to Confluence pages.

Delivery is immediate, hourly, or daily. Hourly waits until the next UTC hour. Daily waits until the next UTC midnight. A schedule runs every five minutes, so a digest can arrive a few minutes after the window closes. Digests list up to 20 items and a count of the rest. Summaries are read again at send time. They are not kept in the queue.

Confluence setup

1. Install ChatHerald on the Confluence site as well as Jira.
2. Open the ChatHerald page in Confluence settings. It is the same admin screen.
3. Use the same webhook, or add another space.
4. Add “Confluence page created or updated”, or a custom rule whose events are page created, page updated, or both.

The message uses the page title and a link. It does not send the page body. Page rows in the delivery log use the key page: followed by the page id.

Troubleshooting

• The test never arrives. Check the URL shape, that the webhook still exists in the space, and the delivery log status code.
• Status 0. The HTTP call did not return a status.
• Other 4xx responses. ChatHerald tries at most three times and does not keep retrying. Three consecutive failures mark the rule as needing attention.
• 429 or 5xx. The app waits briefly, then continues on the five-minute schedule. It stops one hour after the first failure.
• A rule never fires. Confirm it is enabled, the event type matches, the project and status names match, and the JQL matches that issue. An empty changelog on an update matches nothing.
• Licence inactive. You can view rules and the log. Editing and delivery are locked. Rules are not deleted.
• The log looks empty. Rows older than seven days are dropped. The reader shows at most 100 rows.
• You want to retire a webhook. Deleting a rule does not delete the saved webhook URL. Removing a stored webhook from the admin screen is not available yet. Add a new URL for the replacement space.

Scopes

These are the scopes in the app manifest, in the same order. Nothing else is requested. In particular the app does not request write:jira-work, manage:jira-configuration, or a Jira Service Management scope.

The only external fetch host is https://chat.googleapis.com. That declaration is marked as carrying end-user data, because a message can include an issue summary, a short comment excerpt, or a page title.