evidencija-rezija/mailgun-webhook/README.md

# MailGun Webhook Service

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

## Features

### 📧 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

### 🏗️ 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

### 📊 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

### 🧪 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

## Architecture Overview

```
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
```

**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