Pulse/NOTIFICATION_QUICK_REFERENCE.md

Pulse Notification System - Quick Reference

File Structure

Backend Core Files

internal/notifications/
├── notifications.go              (2,358 lines) - Main NotificationManager, email, webhook, apprise
├── webhook_enhanced.go           (605 lines)   - Enhanced webhook support with retry & filtering
├── email_enhanced.go             (415 lines)   - EnhancedEmailManager with SMTP provider support
├── email_providers.go            (217 lines)   - 11 email provider templates (Gmail, SendGrid, etc)
├── email_template.go             (200+ lines)  - HTML email templates
├── webhook_templates.go          (300+ lines)  - 8+ webhook service templates
└── queue.go                      (600+ lines)  - Persistent SQLite notification queue

internal/api/
├── notifications.go              (753 lines)   - HTTP handlers for notification endpoints
└── notification_queue.go         (80+ lines)   - Queue management endpoints

Frontend Files

frontend-modern/src/
├── api/notifications.ts          (201 lines)   - API client for notifications
├── components/Alerts/
│   ├── WebhookConfig.tsx         (300+ lines)  - Webhook config UI
│   └── EmailProviderSelect.tsx   (200+ lines)  - Email provider selector
└── stores/notifications.ts       - Reactive state management

Core Data Structures

EmailConfig

Enabled, Provider, SMTPHost, SMTPPort, Username, Password,
From, To (array), TLS, StartTLS

WebhookConfig

ID, Name, URL, Method, Headers (map), Enabled,
Service (discord/slack/teams/telegram/etc), Template, CustomFields (map)

AppriseConfig

Enabled, Mode (cli/http), Targets (array), CLIPath, TimeoutSeconds,
ServerURL, ConfigKey, APIKey, APIKeyHeader, SkipTLSVerify

Key Methods

NotificationManager

Method	Purpose
SendAlert(alert)	Add alert to queue, start grouping timer
CancelAlert(alertID)	Remove resolved alert
SetEmailConfig(config)	Update & persist email config
SetAppriseConfig(config)	Update & persist apprise config
AddWebhook/UpdateWebhook/DeleteWebhook(...)	Webhook CRUD
GetWebhooks/GetEmailConfig/GetAppriseConfig()	Safe getters
SendTestNotification(method)	Test email/webhook/apprise
ProcessQueuedNotification(notif)	Queue processor callback

Alert Flow

SendAlert() → [Cooldown check] → [Add to pending] → [Start timer] →
[Timer expires] → sendGroupedAlerts() → [Email/Webhook/Apprise async] →
[Queue if available] → [Retry on failure]

API Endpoints

Configuration

• GET /api/notifications/email - Get email config (masked)
• PUT /api/notifications/email - Update email config
• GET /api/notifications/webhooks - List webhooks
• POST /api/notifications/webhooks - Create webhook
• PUT /api/notifications/webhooks/{id} - Update webhook
• DELETE /api/notifications/webhooks/{id} - Delete webhook
• GET /api/notifications/apprise - Get apprise config
• PUT /api/notifications/apprise - Update apprise config

Templates & Providers

• GET /api/notifications/email-providers - Email provider list
• GET /api/notifications/webhook-templates - Webhook templates

Testing & Monitoring

• POST /api/notifications/test - Test notification (email/webhook)
• POST /api/notifications/webhooks/test - Test specific webhook
• GET /api/notifications/webhook-history - Delivery history
• GET /api/notifications/health - Queue & health status
• GET /api/notifications/dlq - Dead letter queue
• GET /api/notifications/queue/stats - Queue statistics
• POST /api/notifications/dlq/retry - Retry DLQ item
• POST /api/notifications/dlq/delete - Delete DLQ item

Email Providers

1. Gmail / Google Workspace (STARTTLS 587, App Password)
2. SendGrid (STARTTLS 587, apikey username)
3. Mailgun (STARTTLS 587)
4. Amazon SES (STARTTLS 587)
5. Microsoft 365 (STARTTLS 587, App Password)
6. Brevo (STARTTLS 587)
7. Postmark (STARTTLS 587, token auth)
8. SparkPost (STARTTLS 587, SMTP_Injection)
9. Resend (STARTTLS 587)
10. SMTP2GO (STARTTLS 587)
11. Custom SMTP

Webhook Services

1. Discord - Embeds with colors, fields
2. Telegram - Markdown, requires chat_id in URL
3. Slack - Blocks, section fields
4. Microsoft Teams - Adaptive Cards
5. PagerDuty - Event API with routing key
6. Gotify - Title + message + priority
7. Pushover - Custom app/user tokens
8. ntfy.sh - Plain text with headers

Security Features

SSRF Protection

• DNS resolution required
• Blocks: localhost, 127.*, private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• Blocks: link-local (169.254., fe80::), cloud metadata (169.254.169.254)
• Max 3 redirects

Rate Limiting

• Email: 60 per minute (configurable)
• Webhooks: 10 per minute per URL

Retry Logic

• Email: Up to 3 attempts, 5s delay
• Webhooks: Exponential backoff 1s→2s→4s→8s→16s→30s (max)
• Queue: Configurable max attempts, DLQ for failures

Constants

Setting	Default	Notes
Webhook timeout	30s	10s for tests
Webhook response limit	1 MB	Prevents memory exhaustion
Email SMTP timeout	10s dial, 30s total	Both TLS & STARTTLS
Cooldown	5 minutes	Per-alert grace period
Grouping window	30 seconds	Alert batching window
Email rate limit	60/minute	Configurable
Webhook rate limit	10/minute per URL	Configurable
Queue processor	5 seconds	Retry interval
Queue cleanup	1 hour	Remove old entries

Template Variables

For webhook/email templates, available fields:

{{.ID}} {{.Level}} {{.Type}} {{.ResourceName}} {{.ResourceID}}
{{.Node}} {{.Instance}} {{.Message}} {{.Value}} {{.Threshold}}
{{.ValueFormatted}} {{.ThresholdFormatted}} {{.StartTime}} {{.Duration}}
{{.Timestamp}} {{.ResourceType}} {{.Acknowledged}} {{.AckTime}}
{{.AckUser}} {{.CustomFields}} {{.AlertCount}} {{.Alerts}}

Database Schema (Queue)

notification_queue

• id (TEXT PRIMARY KEY)
• type (TEXT) - email, webhook, apprise
• status (TEXT) - pending, sending, sent, failed, dlq, cancelled
• alerts (TEXT JSON) - Array of alerts
• config (TEXT JSON) - EmailConfig/WebhookConfig/AppriseConfig
• attempts, max_attempts, last_attempt, last_error
• created_at, next_retry_at, completed_at
• Indexes: status, next_retry_at (pending), created_at

notification_audit

• Audit trail for all notifications
• alert_ids, alert_count, success flag

Important Notes

Password Handling

• Passwords NEVER logged
• Passwords masked in API responses (get returns empty)
• Passwords preserved on update if empty field sent
• For testing, must include existing password

Webhook URL Templating

• Go template syntax: {{.FieldName}}
• Custom functions: title, upper, lower, printf, urlquery, urlencode, urlpath
• Telegram requires chat_id in URL: ?chat_id={{.ChatID}}
• Service-specific data enrichment (Telegram chat_id, PagerDuty routing_key)

Email Templates

• Single alert: Level-specific colors, detailed metrics
• Grouped: Multiple alerts summary
• Both: Responsive HTML + plain text multipart

Persistent Queue

• SQLite WAL mode for concurrency
• 64MB cache, 5s busy timeout
• Background processor: 5s intervals
• Cleanup job: Hourly
• Dead letter queue for permanently failed items