Notifications¶
Set up personal alert preferences so you are notified when inspections complete, fail, or surface critical findings.
Setting up notifications¶
Go to Notifications (/notifications) in the sidebar.
When you sign in through the console, your preferences are keyed to your verified identity (email) so they follow you across API keys. A caller using a raw API key or service account with no signed-in identity falls back to a preference row keyed to that key.
Channels¶
Slack¶
- In your Slack workspace, go to api.slack.com/apps
- Create a new app → Incoming Webhooks → enable → Add New Webhook to Workspace
- Choose a channel and copy the webhook URL
- Paste the URL into the Slack field on the Notifications page
- Click Test to verify the webhook works
Email¶
Enter your email address. Email delivery requires SMTP to be configured by your administrator.
The Test button for email sends one message, and only to your own address as you are signed in. It is for organization admins, it needs the same outgoing mail settings as email delivery, and each organization may send five test emails an hour. A sixth within the hour is refused with 429 and a Retry-After header. A test sent from an API key rather than a signed-in console session is refused, because a key has no address of its own.
Webhook¶
Enter any HTTP endpoint URL. VirtualSutra will POST a JSON payload signed with an HMAC-SHA256 signature in the X-VirtualSutra-Signature header, so you can verify authenticity on your end.
On-call paging (PagerDuty / OpsGenie)¶
Alongside the Slack / email / webhook channels above, your administrator can enable on-call paging. When enabled, a critical finding or a failed run opens a real incident in PagerDuty or OpsGenie, and the matching resolution closes it again.
Paging credentials are configured by an operator, not in the console
The PagerDuty routing key and the OpsGenie API key are deployment-level settings managed in the Helm values, environment or YAML config - exactly like the Slack webhook for the platform-wide channel. They are not editable anywhere in the console, and no screen ever displays them.
What triggers and what resolves¶
| Event | Effect |
|---|---|
| Critical finding | Opens an incident |
| High finding | Opens an incident - only if your administrator added it to the event list. It is off by default |
| Run failed | Opens an incident |
| Resolved finding | Closes the incident that the matching finding opened |
| Run completed | Closes the incident that a previous Run failed opened for the same run |
The incident carries the run name, the check ID, the affected resource and a link straight back to the run's findings in the console.
Severity mapping¶
| VirtualSutra severity | PagerDuty | OpsGenie |
|---|---|---|
| Critical | critical | P1 |
| High | error | P2 |
| Medium | warning | P3 |
| Low | info | P4 |
Personal paging targets¶
Each person can also point paging at themselves rather than only at the shared rota, using three optional fields:
| Field | Effect |
|---|---|
| PagerDuty user ID | Your PagerDuty user id. Included with the incident so it can be routed to you |
| OpsGenie responder | Your OpsGenie username. The alert is assigned to you as a responder |
| Personal severity threshold | Optional. Critical, High, Medium or Low |
Three things are worth knowing:
- Leaving all three blank means no personal paging. There is no separate on/off switch - filling in an identifier is the opt-in. This is the default for everyone.
- Your threshold can only narrow, never widen. If your administrator's channel pages on
criticalonly, setting yours tolowdoes not start paging you on low-severity findings. Setting yours tocriticalwhen the deployment pages onhighdoes stop the high pages reaching you. - You can only be paged through a channel your administrator has already enabled and credentialled. Filling in a PagerDuty user id on a deployment with PagerDuty disabled does nothing.
The three fields live in the On-call paging section of the Notifications page. Your administrator sees the same channels, read-only, under Settings > Integrations > On-call Paging.
Send Test Page does not work yet
The Send Test Page button on the administrator's On-call Paging card is wired up in the console, but the API behind it only accepts the email and webhook channels today - a test page to PagerDuty or OpsGenie comes back as a 400 Unsupported channel error. Verify paging with a real event until the backend adds the two channels.
Events¶
| Event | Trigger |
|---|---|
| Run completed | An inspection run finishes successfully |
| Run failed | A run encounters a fatal error |
| Critical finding | A critical severity finding is discovered |
| High finding | A high severity finding is discovered |
| Compliance regression | A compliance framework's score drops against the previous run |
High finding and Compliance regression are opt-in: the form leaves them unticked until you tick them. There is no personal subscription for a run starting.
Deep links¶
Slack and email notifications include direct links back into the console: a View Findings button (Slack) or a linked call-to-action (email) that takes you straight to the run's findings, plus a Download Report link where a report is available. Critical-severity email notifications also get a [N CRITICAL] prefix on the subject line so they stand out in an inbox.
Webhook payloads carry the same links in a ui_urls field alongside an api_version field. Both are covered by the existing HMAC signature, so verifying the payload signature also verifies these URLs weren't tampered with.
Testing a channel¶
Click Test next to any enabled channel. The console routes this request through the server to avoid browser CORS restrictions.
A failed test reports the kind of error only (for example a timeout or a refused connection), never the text of the error, because that text can contain a webhook address or a routing key.
Saving preferences¶
Click Save preferences. An unsaved-changes indicator shows when you have changes that have not been saved yet.
Platform-level notifications
Your personal preferences control notifications to you. Your administrator may also have configured platform-level alerts (Slack channel, mailing list) that fire regardless of individual preferences.