Skip to content

Notification System Overview

The CyferWall Engage Backend features a powerful, template-driven notification system designed for reliability, ease of use, and comprehensive coverage of customer communication needs.

🎯 Key Features

⚡ Ultra-Simple API

// Send notification in one line
await notifications.email('case-received-customer', 'user@example.com', { caseNumber: 'CW-2025-001' })

🎨 Template-Driven

  • Handlebars templates with rich formatting
  • Automatic variable validation
  • Category-based organization
  • Easy testing and preview

🔄 Multi-Channel Support

  • Email notifications (primary channel)
  • SMS notifications (urgent cases)
  • Webhook notifications (external integrations)
  • Extensible architecture for additional channels

🛡️ Robust Error Handling

  • Graceful failure with detailed error messages
  • Consistent response format across all methods
  • Comprehensive logging for debugging
  • Automatic retries (configurable)

🏗️ Architecture

graph TB
    A[Application Code] --> B[Ultra-Simple API]
    B --> C[Notification Service]
    C --> D[Template Manager]
    D --> E[Template Files]

    C --> F[Email Provider]
    C --> G[SMS Provider] 
    C --> H[Webhook Service]

    I[Handlebars Engine] --> D
    J[Variable Validation] --> D
    K[Error Handling] --> C

    subgraph "Template Categories"
        E1[Customer Templates]
        E2[Internal Templates] 
        E3[Support Templates]
        E4[Operations Templates]
    end

    E --> E1
    E --> E2
    E --> E3
    E --> E4

📂 Template Organization

Templates are organized by audience and purpose:

templates/notifications/
├── customer/          # Customer-facing notifications
│   ├── case-received-customer.template.json
│   ├── case-updated-customer.template.json
│   └── case-escalated-customer.template.json
├── internal/          # Internal staff notifications
│   ├── case-assigned-staff.template.json
│   ├── case-urgent-staff.template.json
│   └── case-overdue-staff.template.json  
├── support/           # Support team notifications
│   ├── case-escalated-support.template.json
│   └── case-priority-support.template.json
├── operations/        # Operations team notifications
│   ├── system-metrics-ops.template.json
│   └── case-volume-ops.template.json
└── html/             # HTML template files
    ├── case-received-customer.html
    ├── case-updated-customer.html
    └── ...

🚀 Quick Start Examples

Basic Email Notification

import { notifications } from '@/util/notifications/ultra-simple'

// Send customer notification
const result = await notifications.email(
  'case-received-customer',
  'john@example.com',
  {
    caseNumber: 'CW-2025-001',
    customerName: 'John Doe',
    issueType: 'Technical Support',
    urgency: 'HIGH'
  }
)

if (result.success) {
  console.log('✅ Notification sent successfully')
} else {
  console.error('❌ Failed to send notification:', result.error)
}

Multi-Channel Notification

// Send both email and SMS for urgent cases
const sendUrgentNotification = async (case, customer) => {
  // Send detailed email
  const emailResult = await notifications.email(
    'case-urgent-customer', 
    customer.email, 
    {
      caseNumber: case.caseNumber,
      customerName: customer.name,
      urgency: case.urgency,
      escalationTime: '4 hours'
    }
  )

  // Send brief SMS
  const smsResult = await notifications.sms(
    customer.phone,
    `URGENT: Your case ${case.caseNumber} requires immediate attention. Check your email for details.`
  )

  // Send webhook to external monitoring
  const webhookResult = await notifications.webhook(
    'https://monitoring.example.com/urgent-case',
    {
      event: 'urgent_case_created',
      caseNumber: case.caseNumber,
      timestamp: new Date().toISOString()
    }
  )

  return { emailResult, smsResult, webhookResult }
}

Notification in Support Controller

import { notifications } from '@/util/notifications/ultra-simple'

export const escalateCaseController = async (req, res) => {
  try {
    // Update case in database
    const updatedCase = await db.supportCase.update({
      where: { caseNumber: req.body.caseNumber },
      data: { 
        urgency: req.body.newUrgency,
        escalatedAt: new Date()
      }
    })

    // Notify customer about escalation
    await notifications.email('case-escalated-customer', updatedCase.email, {
      caseNumber: updatedCase.caseNumber,
      customerName: updatedCase.name,
      originalUrgency: req.body.originalUrgency,
      newUrgency: req.body.newUrgency,
      escalationReason: req.body.reason
    })

    // Alert support team
    await notifications.email('case-escalated-support', 'support@cyferwall.com', {
      caseNumber: updatedCase.caseNumber,
      customerName: updatedCase.name,
      newUrgency: req.body.newUrgency,
      escalationReason: req.body.reason,
      requiresImmediateAttention: req.body.newUrgency === 'CRITICAL'
    })

    res.json({ success: true, message: 'Case escalated successfully' })
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
}

🧪 Testing Templates

The system includes comprehensive testing capabilities:

Test Individual Templates

// Test template rendering
const test = await notifications.test('case-received-customer', {
  caseNumber: 'CW-TEST-001',
  customerName: 'Test User',
  issueType: 'TECHNICAL',
  urgency: 'MEDIUM'
})

console.log('Subject:', test.data.subject)
console.log('Content preview:', test.data.content.substring(0, 200))

Template Information

// Get template requirements
const info = notifications.info('case-escalated-customer')
console.log('Required variables:', info.data.required)
console.log('Optional variables:', info.data.optional)

Available Templates

// List all available templates
const templates = notifications.templates()
templates.forEach(template => {
  console.log(`${template.category}/${template.id}: ${template.name}`)
})

🔧 Configuration

Environment Variables

# Email Provider (choose one)
RESEND_API_KEY="your_resend_key"
SENDGRID_API_KEY="your_sendgrid_key"

# SMS Provider (choose one)  
TWILIO_SID="your_twilio_sid"
TWILIO_TOKEN="your_twilio_token"

# Notification Settings
NOTIFICATION_FROM_EMAIL="noreply@cyferwall.com"
NOTIFICATION_FROM_NAME="CyferWall Support"
NOTIFICATION_RETRY_ATTEMPTS="3"
NOTIFICATION_TIMEOUT_MS="5000"

Service Initialization

import { notifications } from '@/util/notifications/ultra-simple'

// Check if service is ready
if (notifications.isReady()) {
  console.log('✅ Notification service initialized')
} else {
  console.error('❌ Notification service failed to initialize')
}

🎨 Template Features

Handlebars Helpers

Custom helpers for common formatting needs:

{{!-- Date formatting --}}
Case created: {{now "YYYY-MM-DD HH:mm"}}
Days since creation: {{daysSince createdAt}}
Estimated resolution: {{daysUntil estimatedResolution}} days

{{!-- Conditional content --}}
{{#if (eq urgency "CRITICAL")}}
⚠️ This is a critical case requiring immediate attention.
{{/if}}

{{!-- Case-specific formatting --}}
Priority Score: {{priorityScore}}
{{#if assignedStaff}}
Assigned to: {{assignedStaff.name}}
{{else}}
Status: Awaiting assignment
{{/if}}

Variable Validation

Templates automatically validate required variables:

{
  "variables": [
    { "name": "caseNumber", "type": "string", "required": true },
    { "name": "customerName", "type": "string", "required": true },
    { "name": "urgency", "type": "enum", "required": true, "values": ["LOW", "MEDIUM", "HIGH", "CRITICAL"] },
    { "name": "estimatedResolution", "type": "string", "required": false }
  ]
}

📊 Monitoring & Logging

Built-in Logging

All notification attempts are automatically logged:

📧 Email sent - Template: case-received-customer, To: user@example.com, Subject: Case CW-2025-001 Received
📱 SMS sent - To: +1234567890, Message: Your case has been updated...
🔗 Webhook sent - URL: https://external-api.com/webhook, Data keys: event, caseNumber, timestamp

Error Tracking

Failed notifications are logged with detailed error information:

❌ Email failed: Template not found: invalid-template-id
❌ SMS failed: Invalid phone number format: +invalid
❌ Webhook failed: Connection timeout to https://unreachable-api.com

Performance Monitoring

Track notification performance in your monitoring system:

const start = Date.now()
const result = await notifications.email(templateId, email, data)
const duration = Date.now() - start

// Log to your monitoring system
metrics.timing('notification.email.duration', duration)
metrics.increment(result.success ? 'notification.email.success' : 'notification.email.failure')

🔒 Security Considerations

Email Security

  • SPF/DKIM/DMARC records properly configured
  • Rate limiting to prevent abuse
  • Input sanitization in templates
  • No sensitive data in template variables

Template Security

  • Handlebars escaping enabled by default
  • Variable validation prevents injection
  • Template isolation prevents cross-template access
  • Read-only template files in production

🚀 Next Steps

  1. Quick Start Guide - Send your first notification in 5 minutes
  2. Template Management - Learn about template structure and creation
  3. Integration Guide - Integrate notifications throughout your application
  4. API Reference - Complete API documentation

Ready to start sending notifications? Quick Start Guide →