Senyi Labs
Herald documentation
Everything you need to send Jira notifications to Google Chat.
1. Requirements
- Jira Cloud, with Herald installed from the Atlassian Marketplace.
- A Google Workspace account. Incoming webhooks are not available for personal Gmail accounts.
- Incoming webhooks allowed in your Workspace. If you can't find Webhooks in a space, ask your Workspace admin to turn on Allow users to add incoming webhooks under admin.google.com → Apps → Google Workspace → Google Chat → Chat apps.
2. Create a webhook in Google Chat
- Open the Google Chat space that should receive notifications.
- Click the space name at the top, then Apps & integrations.
- Click Webhooks → Add webhook. Name it, for example, "Jira". The avatar is optional.
- Click Save, then copy the webhook URL. It starts with
https://chat.googleapis.com/v1/spaces/.
Treat the webhook URL like a password: anyone with it can post to the space. Herald stores it in Atlassian's encrypted secret storage and never shows it again.
3. Connect the space in Jira
- In Jira, go to Settings (⚙) → Apps and choose Herald – Google Chat notifications in the left menu.
- Click Add connection, give it a name and paste the webhook URL.
- Choose filters and events (below), then click Add connection.
- Click Send test message. A message should appear in the space within seconds.
A connection sends to one space. Add more connections to route different projects or events to different spaces. One Jira change can go to several spaces.
4. Choose which issues
All filters are optional; an empty filter means "any". An issue must pass every filter you set.
| Filter | Notes |
|---|---|
| Projects | One or more projects. |
| Issue types | Matched by ID, so renamed or translated issue types keep working. |
| Priorities, components | Any of the selected ones. |
| Labels | Any of them, or all of them. |
| Custom field values | Pick a select-type custom field and its values; any or all of them. |
| JQL | For anything else, e.g. assignee = "Jane Doe". Checked when you save. currentUser() doesn't work, because there is no "current user" when Jira sends an event. |
5. Choose which changes
- Issue created, assigned, resolved, moved, deleted.
- Status changed, optionally only from certain statuses and/or to certain statuses, e.g. only "In Review → Done".
- Fields changed: any field, or only the fields you pick.
- Comments: new, edited, deleted.
- Work logged, links and attachments added or removed.
- Sprints created, started, completed, and versions created and released. These go to connections whose project filter includes the project.
If one edit changes several things at once, for example status and resolution, the space gets a single message listing them.
6. Noise control
- Combine bulk changes (on by default): normal changes are sent immediately. During a bulk edit, the first three are sent as usual and then one summary lists the whole edit.
- Ignore changes made by Automation for Jira and other apps.
- Ignore changes made by chosen people, for example an integration account.
- Skip private content (on by default): issues with a security level, comments restricted to a group or role, and internal service-desk comments are never sent.
- Pause a connection to stop it temporarily without losing its settings.
7. How messages look
- Cards show the issue key, summary, issue type, what changed, the fields you pick, and an Open in Jira button. Fields can be collapsed behind "show more".
- Compact messages use one short line per update instead of a card.
- One thread per issue (on by default): later updates are posted as replies under the issue's first message. Turn it off to post every update as a new message.
- People are always shown by name, never by account ID.
8. Project settings for project admins
Project administrators can manage notifications for their own project under Project settings → Apps → Google Chat notifications (Herald). Those connections always cover only that project. Jira administrators see them in Herald's global settings, marked with the project they belong to.
9. Delivery log, health and failure alerts
- Delivery log: every connection keeps its latest 100 messages with time, issue, what changed and whether it was delivered. It refreshes automatically while open.
- Health badge: Working, Failing (with the reason) or Nothing sent yet.
- Retries: if Google Chat is busy or briefly unavailable, Herald retries automatically. Messages to one space are sent one at a time to stay within Google's limit of about one message per second per space.
- Failure alerts: when a connection starts failing, the people under Failure alerts get an email from Jira, a daily reminder while it stays broken, and an email when it recovers. By default this is whoever set Herald up.
10. Troubleshooting
| Problem | What to do |
|---|---|
| "Google Chat rejected the webhook" | The webhook was deleted from the space, the URL was copied incompletely, or your Workspace admin turned off incoming webhooks. Create a new webhook and paste it under Edit. |
| No Webhooks option in the space | Incoming webhooks are disabled in your Workspace, or you're using a personal Gmail account. See Requirements. |
| Test message works, but no Jira updates arrive | Check the connection's filters and events, and that it isn't paused. If it uses JQL, check that the issue matches it in Jira's search. |
| An update seems missing | With One thread per issue on, updates appear as replies in the issue's thread. Also check the delivery log. |
| A comment wasn't sent | It was probably restricted or internal, and Skip private content is on. |
11. FAQ
Can Herald send personal messages to individual people?
Not yet. Herald posts to Chat spaces. Personal notifications, buttons on cards and link previews are planned.
Does Herald change anything in Jira?
No. Herald only reads Jira data. Its one other permission sends Jira's own notification email for failure alerts.
Where is my data stored?
On Atlassian's Forge platform. See the privacy policy and security page.
I need help
See Support.