Notification Configuration Guide

For: Shielda users and administrators Last Updated: 2026-04-03

For: Shielda users and administrators Last Updated: 2026-04-03

---

Table of Contents

Overview Notification Channels Email Notifications (Default) Slack Notifications Webhook Notifications In-App Notifications SSE Real-Time Events Event Types Notification Routing & Severity Organization Settings Troubleshooting

---

Overview

Shielda's notification system supports 5 independent channels that fire in parallel. Each notification event is dispatched to all configured channels simultaneously (fire-and-forget). If one channel fails, others still deliver.

Architecture

Key Principle

Email is the default and fallback channel. Even if no other channels are configured, critical notifications are always sent via email to the organization admin. Users can add Slack, webhooks, and other channels on top of email — but email is always the baseline.

---

Notification Channels

Channel Setup Required Real-Time Persistent Default Email SMTP or Email API vars No (async) Yes (in inbox) ✅ Always on Slack Incoming webhook URL Near real-time Yes (in channel) Optional Webhooks Endpoint URL Near real-time Depends on receiver Optional In-App None Yes (SSE-backed) Yes (in database) ✅ Always on SSE None (browser auto-connects) Yes No (live stream) ✅ Always on

---

Email Notifications (Default)

Setup

Email requires either SMTP or API configuration (see Environment Variables):

SMTP Mode (recommended for self-hosted):

API Mode (recommended for SaaS):

What Triggers Emails

Event Email Sent Controlled By Critical finding discovered ✅ Always alertCritical (default: true) High-severity finding ✅ If enabled alertCritical setting Agent goes offline ✅ If enabled alertOffline (default: true) Agent error ✅ If enabled alertOffline setting Security contract generated ✅ If enabled alertContract (default: false) Security contract approved/rejected ✅ If enabled alertContract setting Scan completed ❌ Not by default Available via webhooks/Slack Scan failed ✅ Always Not configurable

Email Recipients

Primary: Organization notifEmail (set in Settings → Notifications) Alerts: Organization alertEmail (separate alert address, optional) Fallback: If no notification email is set, uses the org admin's email

---

Slack Notifications

Setup

Create a Slack Incoming Webhook: - Go to api.slack.com/messaging/webhooks - Create a new app or use existing - Add "Incoming Webhooks" feature - Create a webhook for your desired channel - Copy the webhook URL

Configure in Shielda: - Go to Settings → Notifications - Paste the webhook URL in Slack Webhook URL - Optionally set the Slack Channel override - Click Save

Message Format

Slack notifications use rich formatting: 🔴 Critical findings — Red sidebar, @channel mention 🟠 High findings — Orange sidebar 🟡 Medium findings — Yellow sidebar 🔵 Info — Blue sidebar ✅ Resolved — Green sidebar

Each message includes: Event type and severity Service name and finding title Direct link to the finding/scan in the dashboard Timestamp

Testing

After configuring, click Send Test Notification to verify the webhook is working.

---

Webhook Notifications

Setup

Go to Settings → Webhooks Click Add Webhook Endpoint Enter: - URL: Your HTTP(S) endpoint - Secret: Shared secret for HMAC signature verification - Events: Select which event types to receive (or "All") Click Save

Payload Format

Signature Verification

Each webhook request includes: X-Shielda-Signature-256 — HMAC-SHA256 of the request body using your webhook secret (sha256=<hex) X-Shielda-Timestamp — Unix timestamp (for replay protection)