Skip to content

Notifications & Alerting

Notification Integrations, Alert Rules, and Incident Response Configuration

Document Version: 1.1.0
Last Updated: 2026-04-19

1. Overview

MazeVault provides a comprehensive notification system that alerts operators about critical events such as certificate expirations, secret rotation failures, and security incidents. Notifications can be delivered through multiple channels simultaneously.

Weekly Expiry Reports (v1.0.38+)

MazeVault can generate automated weekly reports listing all certificates and secrets expiring within 60 days. Reports are delivered to all enabled notification channels simultaneously. Configure recipients and trigger reports manually from System Outputs → Reports. See the Release Notes for details.

Supported Notification Channels

Channel Description Authentication
Email (Office365 OAuth2) Email via Microsoft Graph API — recommended for Office365 environments Azure AD App Registration (OAuth2 client credentials)
Email (SMTP) Legacy SMTP-based email notifications with HTML support SMTP credentials (environment variables)
Microsoft Teams Incoming Webhook connector messages Webhook URL
Slack Incoming Webhook messages with Markdown formatting Webhook URL
JIRA Automatic issue creation in JIRA projects Email + API Token (Basic Auth)
Generic Webhook HTTP POST to any URL with JSON payload URL-based

2. Configuration

2.1 Email Configuration

MazeVault supports two email transport methods. Office365 OAuth2 is recommended for organizations using Microsoft 365. When enabled, it takes priority over SMTP.

Sends email via Microsoft Graph API using OAuth2 client credentials flow. No SMTP passwords needed.

Prerequisites:

  1. Azure AD App Registration with Mail.Send application permission
  2. Admin consent granted for the permission
  3. (Recommended) Application Access Policy in Exchange Online to restrict sender mailbox
Variable Required Description Example
O365_EMAIL_ENABLED Yes Set to true to enable true
O365_TENANT_ID Yes Azure AD tenant ID 12345678-abcd-...
O365_CLIENT_ID Yes App registration client ID 87654321-dcba-...
O365_CLIENT_SECRET Yes* Client secret ***
O365_SENDER_EMAIL Yes Sender email (user or shared mailbox) noreply@company.com
O365_AUTH_METHOD No Auth method (default: client_secret) client_secret

* Required for client_secret auth. For Azure AKS, use managed_identity instead.

Authentication methods:

Method O365_AUTH_METHOD Best For
Client Secret client_secret Standard deployments
Certificate certificate On-premise, enhanced security
Managed Identity managed_identity Azure AKS (no credentials needed)

Email Transport Status

After configuration, check System Outputs → Notifications tab for the email transport status indicator showing "📧 Email Transport: Office365 OAuth2 ✅".

Option B: SMTP (Legacy)

Variable Required Description Example
SMTP_HOST Yes SMTP server hostname smtp.office365.com
SMTP_PORT Yes SMTP server port 587
SMTP_USERNAME Yes SMTP authentication username noreply@company.com
SMTP_PASSWORD Yes SMTP authentication password ***
SMTP_FROM Yes Sender email address noreply@company.com

Testing Email Configuration

After setting environment variables, restart the MazeVault backend and use the Test button in System Outputs → Notifications to verify delivery.

Priority Logic

1. O365_EMAIL_ENABLED=true → Office365 via Microsoft Graph API
2. SMTP_HOST configured    → Legacy SMTP
3. Neither configured      → Email notifications disabled

2.2 Notification Integrations (UI)

Navigate to System Outputs → Notifications tab to configure notification channels.

Adding a New Integration

  1. Click Add Integration
  2. Select the integration type (Slack, Teams, JIRA, Webhook, Email)
  3. Enter a descriptive name
  4. Fill in the required configuration fields
  5. Optionally enable Weekly Expiry Report checkbox
  6. Click Save Integration

JIRA Configuration

Field Description Example
Jira Base URL Your Atlassian instance URL https://company.atlassian.net
Email Atlassian account email operator@company.com
API Token Atlassian API token (generate here) ATATT3x...
Project Key JIRA project key for issue creation SEC

JIRA Test Creates Real Issues

The Test button creates an actual JIRA issue in the configured project. Use a test project during initial setup.

Slack Configuration

Field Description Example
Webhook URL Slack Incoming Webhook URL https://hooks.slack.com/services/T.../B.../xxx
Channel (optional) Override default channel #security-alerts

Microsoft Teams Configuration

Field Description Example
Webhook URL Teams Incoming Webhook URL https://outlook.office.com/webhook/...

Generic Webhook Configuration

Field Description Example
URL Target endpoint URL https://api.pagerduty.com/events

Webhook payload format: 

{
  "subject": "Alert subject",
  "message": "Alert body text"
}

3. Alert Rules & Triggers

3.1 Automatic Alerts (Daily Check)

MazeVault runs a daily check (every 24 hours) for the following conditions:

Certificate Expiry Alerts

Condition Alert Triggered?
Certificate expires within 30 days, auto-renewal disabled ✅ Yes
Certificate expires within 30 days, auto-renewal enabled but failed ✅ Yes
Certificate expires within 30 days, auto-renewal enabled and successful ❌ No
Certificate already expired ❌ No (only pre-expiry alerts)

Alert recipients:

  1. Legacy environment variable recipients (ADMIN_EMAIL, TEAMS_WEBHOOK_URL)
  2. Organization incident contacts
  3. All active notification integrations (category: notification)

Secret Rotation Failure Alerts

Condition Alert Triggered?
Rotation config status = failed and enabled = true ✅ Yes
Rotation config status = success ❌ No
Rotation config enabled = false ❌ No

3.2 Incident Notifications (Real-time)

When a security incident is detected and created, notifications are sent immediately to:

  1. Audit log — INCIDENT_DETECTED event recorded
  2. Incident contacts — Email sent to all configured contacts
  3. Notification integrations — All active notification integrations receive the alert

Incident notification includes: - Incident type and severity - Affected resource name - Detection timestamp - Change details

3.3 Rotation Failure Notifications (Per-Secret)

Individual secret rotation configurations can have dedicated notification emails:

  • Configured per rotation config in the secret rotation settings
  • Sent via email only when a rotation execution fails
  • Independent of organization-level notification integrations

3.4 Weekly Expiry Report (Scheduled)

A comprehensive report is generated and sent every Monday at 7:00 AM CET:

Report contents:

  • Certificates expiring within the next 60 days
  • Secrets with rotation due within the next 60 days
  • Total certificate and secret counts

Delivery channels:

Channel Format Configuration
Email HTML (formatted table) System Outputs → Weekly Expiry Report → Recipients
Slack/Teams/Webhook/JIRA Plain text summary Integrations with "Enable Weekly Expiry Report" checked

4. Incident Response Configuration

4.1 Incident Contacts

Navigate to System Outputs → Incident Response to manage contacts.

Incident contacts receive email notifications for: - Certificate expiry alerts - Rotation failure alerts - Security incidents

Each contact has: - Name — Contact person name - Email — Notification email address - Role — Organizational role (e.g., Security Lead, DevOps) - Priority — Contact priority order

4.2 Legacy Environment Variables

For backward compatibility, the following environment variables are also checked:

Variable Description
ADMIN_EMAIL Fallback admin email for all alerts
TEAMS_WEBHOOK_URL Fallback Teams webhook for all alerts

These are checked in addition to configured integrations and incident contacts.

5. Notification Delivery Order

When an alert is triggered, notifications are sent in this order:

1. Legacy environment variables (ADMIN_EMAIL, TEAMS_WEBHOOK_URL)
2. Organization incident contacts (email only)
3. Active notification integrations:
   a. JIRA → Creates issue
   b. Teams → Sends webhook message
   c. Slack → Sends webhook message
   d. Webhook → Sends HTTP POST
   e. Email → Sends to configured recipients

Best-Effort Delivery

Each channel is independent. If one channel fails (e.g., JIRA API is down), other channels still receive the notification. Failures are logged in the backend logs.

6. Testing Integrations

Using the Test Button

  1. Navigate to System Outputs → Notifications
  2. Find the integration card
  3. Click Test
  4. Wait for the result (button shows "Testing..." during the request)
  5. A toast notification shows success or the specific error message

What the Test Does

Integration Test Action
JIRA Creates a real "Task" issue titled "Test Notification from MazeVault"
Teams Sends a test message to the webhook
Slack Sends a test message to the webhook
Webhook Sends a test JSON payload to the URL
Email Sends a test email to each configured recipient

7. Troubleshooting

Common Issues

Symptom Cause Solution
"Test notification failed" Invalid credentials or URL Check integration configuration, verify API tokens
No JIRA issues created Wrong project key or permissions Verify project key exists and API token has create issue permission
Teams/Slack messages not arriving Webhook URL expired or disabled Regenerate the webhook URL in Teams/Slack admin
Emails not delivered (SMTP) SMTP configuration incorrect Verify SMTP_* environment variables, check firewall rules
Emails not delivered (O365) OAuth2 configuration incorrect Verify O365_* env vars, check Mail.Send permission and admin consent
O365 "403 Forbidden" Missing Mail.Send permission Grant Mail.Send application permission + admin consent in Azure AD
O365 "404 Not Found" Invalid sender mailbox Verify O365_SENDER_EMAIL is a valid user or shared mailbox
Weekly report not sent No recipients configured Add recipients in System Outputs → Weekly Expiry Report

Checking Notification Logs

Backend logs include detailed notification delivery information:

[NotificationScheduler] Certificate CN=example.com expiring on 2026-04-15
[NotificationScheduler] Failed to send JIRA notification (integration=abc123): jira api error: 401
[IncidentService] Failed to send Teams notification (integration=def456): teams webhook failed with status: 410
[WeeklyReportService] Failed to send report to channel slack: no webhook_url in Slack integration xyz789

Filter logs by these prefixes to diagnose notification issues: - [NotificationScheduler] — Daily expiry and rotation checks - [IncidentService] — Incident notifications - [WeeklyReportService] — Weekly report delivery