feat: implement MailGun webhook service for logging email events

Implemented a production-ready TypeScript/Express.js service to receive and log MailGun webhook events (delivered, failed, opened, clicked, etc.). Key features: - Webhook endpoint (POST /webhook) with comprehensive event logging - Full TypeScript type definitions for all MailGun event types - Prometheus metrics integration for monitoring - Health check endpoint (GET /ping) - Comprehensive Jest test suite with 87.76% coverage - Docker containerization with build scripts Removed template/example code: - All SQL/MSSQL dependencies and related code - Example auth router and middleware - PRTG metrics support (simplified to Prometheus only) - Unused middleware (CORS, IP whitelist, request parsing/validation) - Template documentation (kept only MailGun webhook API spec) The service is clean, minimal, and focused solely on receiving and logging MailGun webhook events to the console. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-02 20:56:22 +01:00
parent 4371a9a20a
commit 7aeea9353d
39 changed files with 12015 additions and 14 deletions
--- a/mailgun-webhook/README.md
+++ b/mailgun-webhook/README.md
@@ -1,23 +1,185 @@
-# Mailgun Webhook Handler
+# MailGun Webhook Service

-This workspace contains the Mailgun webhook handler service for processing email events related to the Evidencija Režija tenant notification system.
+A production-ready TypeScript/Express.js service for receiving and logging MailGun webhook events with:
+- **Webhook Processing**: Handles all MailGun email event types (delivered, failed, opened, clicked, etc.)
+- **Structured Logging**: Console logging with detailed event information
+- **Monitoring**: Built-in Prometheus metrics and health checks
+- **Testing**: Complete Jest test suite with comprehensive webhook event coverage
+- **Docker Ready**: Containerized deployment with health monitoring

-## Purpose
+## Features

-This service handles email verification and status updates by:
- Detecting new tenant email addresses (EmailStatus.Unverified)
- Sending verification emails via Mailgun
- Updating email status to VerificationPending
- Processing webhook events from Mailgun (bounces, complaints, etc.)
+### 📧 MailGun Webhook Integration
+- **Event Types**: Supports all MailGun webhook events:
+  - `delivered` - Email successfully delivered
+  - `failed` - Delivery failed (temporary or permanent)
+  - `opened` - Email opened by recipient
+  - `clicked` - Link clicked in email
+  - `bounced` - Email bounced back
+  - `complained` - Recipient marked as spam
+  - `unsubscribed` - Recipient unsubscribed
+- **Data Logging**: Comprehensive console logging with structured formatting
+- **Type Safety**: Full TypeScript definitions for all event types

-## Architecture
+### 🏗️ Infrastructure
+- **TypeScript**: Full type safety and modern JavaScript features
+- **Express.js**: Fast, minimalist web framework
+- **Logging**: Structured logging with debug support and detailed event formatting
+- **Health Checks**: Built-in `/ping` endpoint for monitoring

-This is a separate system from the Next.js web-app that communicates via the shared MongoDB database.
+### 📊 Monitoring & DevOps
+- **Prometheus Metrics**: Built-in metrics collection at `/metrics`
+- **Docker**: Complete containerization setup
+- **Source Maps**: Debugging support for production
+- **Hot Reload**: Development server with auto-restart

-## Setup
+### 🧪 Testing & Quality
+- **Jest**: Comprehensive unit tests for all webhook event types
+- **TypeScript**: Full type coverage
+- **Test Structure**: Mirror source structure for easy navigation
+- **CI Ready**: Tests configured for continuous integration

-TBD
+## Architecture Overview

-## Environment Variables
+```
+src/
+├── entry.ts                      # Application bootstrap
+├── app.ts                        # Express app configuration
+├── routes/
+│   ├── webhookRouter.ts          # MailGun webhook handler
+│   ├── pingRouter.ts             # Health check endpoint
+│   ├── metricsRouter.ts          # Prometheus metrics
+│   └── errorRouter.ts            # Error handling
+├── middleware/
+│   └── InitLocalsMiddleware.ts   # Request context initialization
+├── types/
+│   ├── MailgunWebhookEvent.ts    # MailGun event type definitions
+│   └── enums/SupportedRoutes.ts  # Route path constants
+└── lib/
+    ├── logger.ts                 # Structured logging utilities
+    └── metricsCounters.ts        # Prometheus metrics definitions
+```

-TBD
+**API Endpoints:**
+- `POST /webhook` - Receives MailGun webhook events
+- `GET /ping` - Health check endpoint
+- `GET /metrics` - Prometheus metrics
+
+For detailed API specification, see [docs/MAILGUN_WEBHOOK_API_SPEC.md](docs/MAILGUN_WEBHOOK_API_SPEC.md).
+
+## Quick Start
+
+### 1. Installation
+```bash
+# Install dependencies
+npm install
+
+# Create environment file
+cp .env.example .env
+# Edit .env if needed (defaults work for development)
+```
+
+### 2. Development
+```bash
+# Start development server with hot reload
+npm start
+
+# Server will be running at http://localhost:3000
+```
+
+### 3. Testing the Webhook
+```bash
+# Send a test webhook event
+curl -X POST http://localhost:3000/webhook \
+  -H "Content-Type: application/json" \
+  -d '{
+    "event": "delivered",
+    "timestamp": "1234567890",
+    "token": "test-token",
+    "signature": "test-signature",
+    "recipient": "user@example.com",
+    "domain": "mail.example.com"
+  }'
+
+# Check the console output for logged event data
+```
+
+### 4. Running Tests
+```bash
+# Run tests in watch mode
+npm test
+
+# Run tests once with coverage
+npm run test:ci
+
+# Type checking
+npm run type-check
+```
+
+### 5. Production Build
+```bash
+# Build TypeScript to JavaScript
+npm run build
+
+# Run production server
+npm run run-server
+```
+
+## Configuring MailGun
+
+To start receiving webhook events from MailGun:
+
+1. **Log in to your MailGun account**
+2. **Navigate to Sending → Webhooks**
+3. **Add a new webhook URL**: `https://your-domain.com/webhook`
+4. **Select event types** you want to receive (or select all)
+5. **Save the webhook configuration**
+
+MailGun will start sending events to your service endpoint immediately.
+
+### Webhook Security (Future Enhancement)
+
+For production deployment, you should implement webhook signature verification:
+- Use MailGun's `timestamp`, `token`, and `signature` fields
+- Verify the signature using your MailGun signing key
+- See [MailGun Webhook Security Documentation](https://documentation.mailgun.com/en/latest/user_manual.html#webhooks)
+
+## Docker Deployment
+
+### Building the Docker Image
+```bash
+# Build the image
+./build-image.sh 1.0.0
+
+# The image will be tagged as mailgun-webhook-service:1.0.0
+```
+
+### Running with Docker
+```bash
+# Run the container
+docker run -d \
+  -p 3000:3000 \
+  -e PORT=3000 \
+  -e PROMETHEUS_APP_LABEL=mailgun-webhook-service \
+  --name mailgun-webhook \
+  mailgun-webhook-service:1.0.0
+
+# Check logs
+docker logs -f mailgun-webhook
+```
+
+
+## Monitoring
+
+The service exposes several monitoring endpoints:
+
+- **Health Check**: `GET /ping` - Returns "pong" if service is healthy
+- **Prometheus Metrics**: `GET /metrics` - Prometheus-compatible metrics
+
+## Documentation
+
+- 📧 **[MailGun Webhook API Spec](docs/MAILGUN_WEBHOOK_API_SPEC.md)** - Complete API specification
+
+## License
+
+ISC