An intelligent notification routing system that receives webhooks from various sources (Linear, Sentry, etc.) and uses AI to determine the most appropriate channels for delivery. The system analyzes notification content and routes messages to predefined email channels based on context, priority, and team relevance.

Instead of broadcasting all notifications to everyone, this system:

1. Receives webhooks from external services
2. Analyzes the content using AI (GPT-4)
3. Routes notifications to appropriate channels based on:
   • Content analysis and keywords
   • Priority/severity levels
   • Team assignments
   • Predefined channel descriptions
4. Delivers formatted, actionable messages via email

Each notification includes:

• Clear summary of what happened
• Relevant links in proper format
• Context tailored to the target audience
• Action items when applicable

├── CONFIGURATION.ts      # Channel definitions, webhook config, AI prompts
├── linear-webhook.ts     # HTTP webhook handler for Linear (with GET config page)
├── main.tsx             # (Reserved for future integrations)
└── README.md            # This file

• Webhook Handler: Secure endpoint with HMAC-SHA256 signature verification
• Configuration Page: Visit the webhook URL in browser for setup instructions
• Event Filtering: Skips low-value events (views, reads)
• Rich Data Processing: Handles titles, descriptions, assignees, labels, priorities, teams

• GPT-4 Analysis: Intelligent content analysis for channel selection
• Context-Aware Routing: Considers urgency, technical domain, and team structure
• Fallback Logic: Routes to general channel if AI processing fails
• Reasoning Transparency: Includes explanation of routing decisions

• Multi-Channel Support: Can notify multiple channels for critical issues
• Rich Formatting: HTML emails with structured information
• Branded Messages: Consistent formatting with clear subject prefixes
• Error Handling: Graceful failure handling per channel

Pre-configured channels include:

• Engineering Critical: P0/P1 issues, outages, security incidents
• Engineering General: Feature development, code reviews, technical debt
• Product Team: UX issues, feature requests, business logic
• DevOps & Infrastructure: Deployment, monitoring, performance
• Quality Assurance: Testing, automation, bug reports
• General Notifications: Low-priority and uncategorized items

Set these in your Val Town environment:

• LINEAR_WEBHOOK_SECRET - Your Linear webhook signing secret
• OPENAI_API_KEY - Automatically handled by Val Town's OpenAI integration

Update email addresses in CONFIGURATION.ts to match your organization:

{
  id: 'engineering-critical',
  name: 'Engineering Critical',
  email: 'your-critical-team@company.com', // Update this
  description: '...',
  // ...
}

1. Visit your webhook URL in a browser to see configuration instructions
2. Copy the webhook URL from the configuration page
3. In Linear: Settings → API → Webhooks → Create webhook
4. Paste the URL and copy the signing secret
5. Add the signing secret to Val Town as LINEAR_WEBHOOK_SECRET
6. Select events to monitor (Issues, Comments, Projects recommended)

Create or update a Linear issue to test the integration. Check logs in Val Town for debugging.

1. Receive: Linear sends webhook with HMAC signature
2. Verify: Validate signature using signing secret
3. Parse: Extract relevant data (title, description, priority, labels, etc.)
4. Analyze: Send to GPT-4 with channel descriptions for triage
5. Route: AI selects appropriate channel(s) with reasoning
6. Format: Create tailored message for target audience
7. Deliver: Send email notification(s)
8. Log: Record success/failure for debugging

The AI considers:

• Keywords: Matches against channel-specific keywords
• Priority: Routes high-priority items to critical channels
• Team Context: Considers team assignments and technical domains
• Content Analysis: Analyzes descriptions for technical vs. product issues
• Multi-Channel Logic: Can notify multiple channels for critical issues

Each channel has:

• Description: Detailed explanation of what belongs there
• Keywords: Specific terms that indicate relevance
• Priority Level: High/medium/low for urgency-based routing
• Email Address: Delivery target

• Sentry: Error monitoring and performance alerts
• GitHub: PR reviews, security alerts, deployment status
• Slack: Direct Slack channel delivery (alternative to email)
• PagerDuty: Incident management integration

• Smart Scheduling: Respect time zones and on-call schedules
• Escalation Logic: Auto-escalate if no response within timeframe
• Analytics Dashboard: Track notification patterns and effectiveness
• Custom Rules: User-defined routing rules beyond AI
• Digest Mode: Batch low-priority notifications

When adding new integrations:

1. Create a new webhook handler file (e.g., sentry-webhook.ts)
2. Add configuration to CONFIGURATION.ts
3. Follow the same pattern: verify → parse → triage → deliver
4. Include GET endpoint for configuration instructions
5. Update this README with new features

• Webhook Logs: Check Val Town logs for processing details
• AI Responses: Triage reasoning is logged for transparency
• Email Delivery: Individual channel delivery status is logged
• Signature Verification: Failed authentications are logged with details