Skip to main content

Notifications

Shield can notify you about security threats in real-time via multiple channels: user messages, admin alerts, backend dashboard, and webhooks.

Quick Start​

Enable basic notifications:

{
  "notifications": {
    "user": true,
    "admin": true
  }
}

Now:

  • ✅ Users see why their messages were blocked
  • ✅ You get alerted about security events

Notification Types​

User Notifications​

Inform users when their messages are blocked/flagged.

{
  "notifications": {
    "user": true
  }
}

What users see:

When blocked:

🛑 Message blocked by security filter
Reason: SQL injection detected

Please rephrase your message.

When flagged:

⚠️ Your message was flagged for review

Original message: [message content]
Reason: Suspicious pattern detected

Customize message:

{
  "notifications": {
    "user": true,
    "userMessage": "⚠️ Security filter triggered. Please contact support if this is an error."
  }
}

Admin Notifications​

Get notified when threats are detected.

{
  "notifications": {
    "admin": true,
    "adminChannel": "telegram:@admin"
  }
}

Admin receives:

🚨 Security Alert

Sender: +1555***4567
Channel: whatsapp:customer_support
Direction: inbound
Threat: sql_injection
Action: blocked
Message: "'; DROP TABLE users; --"
Time: 2026-02-04 14:32:15 UTC

Supported admin channels:

  • telegram:@username or telegram:123456789
  • discord:user_id
  • slack:channel_id
  • whatsapp:+15551234567
  • email:admin@company.com

Backend Alerts​

Send alerts to SecureCheck dashboard for centralized monitoring.

{
  "notifications": {
    "backendAlerts": true,
    "backendAlertThreshold": 3,
    "backendAlertWindow": 3600
  }
}

Behavior:

  • Only send alert after 3 violations within 1 hour
  • Prevents spam from noisy users
  • Aggregates related threats

Dashboard features:

  • View all alerts across all bots
  • Filter by type, severity, sender
  • Export for compliance
  • Analytics and trends

Batching​

Batch multiple alerts into single notification:

{
  "notifications": {
    "backendAlertBatching": true,
    "backendAlertBatchSize": 10,
    "backendAlertBatchDelay": 300
  }
}

Sends alert every 10 threats OR every 5 minutes, whichever comes first.

Alert Filtering​

By Severity​

Only alert on critical threats:

{
  "notifications": {
    "admin": true,
    "minSeverity": "high"
  }
}

Severity levels:

  • critical - Active attacks, data leaks
  • high - SQL injection, XSS, prompt injection
  • medium - Suspicious patterns, possible threats
  • low - Minor anomalies, edge cases

By Threat Type​

Only alert on specific threats:

{
  "notifications": {
    "admin": true,
    "alertTypes": [
      "sql_injection",
      "data_leak",
      "prompt_injection"
    ]
  }
}

Ignore less critical threats like spam or rate limits.

By Direction​

Only alert on outbound (data leak) threats:

{
  "notifications": {
    "admin": true,
    "alertDirections": ["outbound"]
  }
}

Or both:

{
  "alertDirections": ["inbound", "outbound"]
}

Notification Channels​

Telegram​

Setup:

  1. Create a Telegram bot or use existing bot
  2. Get your user ID or chat ID
  3. Configure Shield:
{
  "notifications": {
    "admin": true,
    "adminChannel": "telegram:@yourusername"
  }
}

Or by user ID:

{
  "adminChannel": "telegram:123456789"
}

Discord​

Setup:

  1. Get your Discord user ID (enable Developer Mode, right-click user, Copy ID)
  2. Configure Shield:
{
  "notifications": {
    "admin": true,
    "adminChannel": "discord:123456789012345678"
  }
}

Slack​

Setup:

  1. Get Slack channel ID or user ID
  2. Configure Shield:
{
  "notifications": {
    "admin": true,
    "adminChannel": "slack:C12345678"
  }
}

Email​

Setup:

{
  "notifications": {
    "admin": true,
    "adminChannel": "email:admin@company.com"
  }
}

Multiple emails:

{
  "adminChannel": "email:admin@company.com,security@company.com"
}

WhatsApp​

Setup:

{
  "notifications": {
    "admin": true,
    "adminChannel": "whatsapp:+15551234567"
  }
}

Webhooks​

Feature Implemented

Webhooks are fully implemented and ready to use!

Send alerts to external systems via HTTP webhooks.

Basic Webhook​

{
  "notifications": {
    "webhooks": [
      {
        "url": "https://your-server.com/shield-alerts",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer your-secret-token"
        }
      }
    ]
  }
}

Payload sent:

{
  "event": "threat_detected",
  "timestamp": "2026-02-04T14:32:15Z",
  "sender": "+1555***4567",
  "channel": "whatsapp:customer_support",
  "direction": "inbound",
  "threatType": "sql_injection",
  "severity": "high",
  "action": "blocked",
  "message": "***REDACTED***",
  "botId": "bot_abc123"
}

Filtered Webhook​

Only send specific events:

{
  "webhooks": [
    {
      "url": "https://api.company.com/security",
      "events": ["threat_detected", "data_leak"],
      "minSeverity": "high"
    }
  ]
}

Multiple Webhooks​

Route different alerts to different systems:

{
  "webhooks": [
    {
      "url": "https://api.company.com/critical-alerts",
      "events": ["data_leak"],
      "minSeverity": "critical"
    },
    {
      "url": "https://api.company.com/all-alerts",
      "events": ["threat_detected"]
    },
    {
      "url": "https://siem.company.com/ingest",
      "method": "POST",
      "headers": {
        "X-API-Key": "siem-key-123"
      }
    }
  ]
}

Notification Throttling​

Prevent alert fatigue from noisy threats.

Rate Limit Notifications​

{
  "notifications": {
    "admin": true,
    "throttle": {
      "enabled": true,
      "maxAlerts": 10,
      "window": 3600
    }
  }
}

Max 10 admin alerts per hour. After limit, sends summary instead.

Duplicate Detection​

{
  "notifications": {
    "deDuplicate": true,
    "deDuplicateWindow": 300
  }
}

Don't send duplicate alerts within 5 minutes.

Example:

  • User sends DROP TABLE users 10 times
  • First alert sent immediately
  • Next 9 alerts suppressed
  • Summary sent after 5 minutes: "9 similar alerts suppressed"

Alert Content​

Redaction in Alerts​

Alerts respect redaction settings:

{
  "redaction": {
    "enabled": true,
    "mode": "all"
  },
  "notifications": {
    "admin": true
  }
}

Admin sees:

Message: "My API key is sk-***...*** please help"

Instead of:

Message: "My API key is sk-1234567890abcdef please help"

Include Full Message​

Override redaction for admin alerts:

{
  "notifications": {
    "admin": true,
    "adminIncludeFullMessage": true
  }
}
Security Risk

Admins will see unredacted secrets and PII. Use with caution.

Include Context​

Add extra context to alerts:

{
  "notifications": {
    "admin": true,
    "includeContext": {
      "previousMessages": 3,
      "userProfile": true,
      "channelInfo": true
    }
  }
}

Admin sees last 3 messages from user for better context.

Notification Formats​

Compact Format​

{
  "notifications": {
    "admin": true,
    "format": "compact"
  }
}

Output:

🚨 +1555***4567 | inbound | sql_injection | blocked

Detailed Format (Default)​

{
  "format": "detailed"
}

Output:

🚨 Security Alert

Sender: +1555***4567
Channel: whatsapp:support
Direction: inbound
Threat: sql_injection (high)
Action: blocked
Message: "'; DROP TABLE..."
Time: 2026-02-04 14:32:15 UTC
Bot: customer-support-bot

JSON Format​

For programmatic processing:

{
  "format": "json"
}

Complete Configuration Example​

{
  "notifications": {
    "// User Notifications": "",
    "user": true,
    "userMessage": "⚠️ Your message triggered our security filter.",
    
    "// Admin Notifications": "",
    "admin": true,
    "adminChannel": "telegram:@admin",
    "minSeverity": "high",
    "format": "detailed",
    
    "// Backend Integration": "",
    "backendAlerts": true,
    "backendAlertThreshold": 3,
    "backendAlertWindow": 3600,
    
    "// Webhooks": "",
    "webhooks": [
      {
        "url": "https://api.company.com/alerts",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer secret"
        },
        "minSeverity": "high"
      }
    ],
    
    "// Throttling": "",
    "throttle": {
      "enabled": true,
      "maxAlerts": 20,
      "window": 3600
    },
    "deDuplicate": true,
    "deDuplicateWindow": 300
  }
}

Testing Notifications​

Test User Notification​

Send a threat as a regular user:

'; DROP TABLE users; --

You should receive the user notification message.

Test Admin Notification​

/shield test <script>alert('xss')</script>

Admin should receive alert in configured channel.

Test Webhook​

Check webhook endpoint logs to verify payload delivery.

Troubleshooting​

Not Receiving Admin Alerts​

Problem: No notifications in admin channel

Solutions:

  1. Verify admin: true
  2. Check adminChannel format is correct
  3. Test channel access (bot can message channel?)
  4. Check minSeverity isn't filtering everything
  5. Verify threats are actually being detected (/shield status)

Webhook Failing​

Problem: Webhook endpoint not receiving data

Solutions:

  1. Check URL is correct and accessible
  2. Verify HTTPS (Shield requires HTTPS for webhooks)
  3. Check authentication headers
  4. Review Shield logs for webhook errors: 
    grep "webhook" ~/.securecheck/shield/logs/*.log

Too Many Notifications​

Problem: Alert fatigue, too many messages

Solutions:

  1. Enable throttling: 
    {
      "throttle": {
        "enabled": true,
        "maxAlerts": 10,
        "window": 3600
      }
    }
  2. Increase minSeverity to critical
  3. Enable deDuplicate
  4. Filter by alertTypes

Best Practices​

  1. Start with user notifications - Always inform users
  2. Use throttling - Prevent alert fatigue
  3. Filter by severity - Only alert on important threats
  4. Test webhooks - Verify integration works
  5. Monitor dashboard - Check backend for missed alerts
  6. Regular reviews - Adjust thresholds based on volume

Next Steps​