# Webhook Server

Secure Flask-based webhook service for receiving and processing security alerts from Particle IoT devices, with enterprise-grade features including authentication, rate limiting, and comprehensive logging.

## 🎯 Overview

This webhook service provides:
- **Dual Authentication**: HMAC signatures for generic webhooks, Bearer tokens for Particle webhooks
- **Security Hardening**: Rate limiting, security headers, input validation
- **Enterprise Integration**: Docker containerization, Traefik reverse proxy support
- **Monitoring Ready**: Comprehensive logging, health checks, metrics endpoints
- **Notification Support**: Email/SMS alerts with rich formatting

## 🏗️ Architecture

```
Internet ──▶ Traefik ──▶ Webhook Service ──▶ Notifications
             (SSL)      (Docker)           (Email/SMS)
                │
                ├─ Rate Limiting
                ├─ Security Headers  
                ├─ Authentication
                └─ Health Checks
```

### Key Components
- **Flask Application**: Lightweight webhook processor
- **Gunicorn WSGI Server**: Production-grade application server
- **Docker Container**: Isolated, reproducible deployment
- **Traefik Integration**: Automatic SSL, load balancing, monitoring
- **Health Monitoring**: Built-in health checks and status endpoints

## 🔐 Security Features

### Authentication Methods
1. **Particle Webhooks**: Bearer token authentication
   ```
   Authorization: Bearer your-particle-secret
   User-Agent: ParticleBot/1.0
   ```

2. **Generic Webhooks**: HMAC-SHA256 signature verification
   ```
   X-Hub-Signature-256: sha256=computed-hmac-signature
   ```

### Security Hardening
- **Rate Limiting**: 10 requests/minute average, 20 burst
- **Security Headers**: XSS protection, content type sniffing prevention
- **Input Validation**: JSON schema validation, required field checking
- **Non-root Container**: Runs as unprivileged user
- **Minimal Attack Surface**: Only required packages installed

### Network Security
- **TLS Termination**: Handled by Traefik reverse proxy
- **Internal Networks**: Container-to-container communication only
- **No Direct Exposure**: No ports directly exposed to internet

## 🚀 Quick Start

### Prerequisites
- Docker and Docker Compose
- Traefik reverse proxy (with external network)
- Gmail account with app password
- Domain name pointing to your server

### 1. Clone and Setup
```bash
# Clone the repository
git clone https://github.com/yourusername/security-device-system.git
cd security-device-system/webhook-server

# Copy environment template
cp .env.example .env
```

### 2. Configure Environment
```bash
# Edit environment variables
nano .env

# Required variables:
FLASK_SECRET_KEY=your-flask-secret-key
WEBHOOK_SECRET=your-hmac-webhook-secret  
PARTICLE_WEBHOOK_SECRET=your-particle-bearer-secret
SMTP_EMAIL=your-email@gmail.com
SMTP_PASSWORD=your-gmail-app-password
RECIPIENT_EMAIL=your-phone@carrier.com
```

### 3. Deploy Service
```bash
# Build and start the service
docker compose up -d --build

# Check service status
docker compose ps

# Monitor logs
docker compose logs -f webhook-service
```

### 4. Verify Deployment
```bash
# Test health endpoint
curl https://webhook.yourdomain.com/health

# Should return:
# {"status": "healthy", "timestamp": "2024-01-07T..."}
```

## 📝 Configuration

### Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `FLASK_SECRET_KEY` | Flask session encryption key | `openssl rand -hex 32` |
| `WEBHOOK_SECRET` | HMAC secret for generic webhooks | `openssl rand -hex 32` |
| `PARTICLE_WEBHOOK_SECRET` | Bearer token for Particle webhooks | `openssl rand -hex 32` |
| `SMTP_EMAIL` | Gmail address for notifications | `alerts@yourdomain.com` |
| `SMTP_PASSWORD` | Gmail app password (not regular password) | `abcd efgh ijkl mnop` |
| `RECIPIENT_EMAIL` | SMS gateway email for notifications | `5551234567@vtext.com` |

### Generating Secrets
```bash
# Generate secure random secrets
FLASK_SECRET=$(openssl rand -hex 32)
WEBHOOK_SECRET=$(openssl rand -hex 32)
PARTICLE_SECRET=$(openssl rand -hex 32)

echo "FLASK_SECRET_KEY=$FLASK_SECRET"
echo "WEBHOOK_SECRET=$WEBHOOK_SECRET"
echo "PARTICLE_WEBHOOK_SECRET=$PARTICLE_SECRET"
```

### Gmail Setup
1. Enable 2-Factor Authentication on your Google account
2. Go to [Google App Passwords](https://myaccount.google.com/apppasswords)
3. Generate app password for "Webhook Service"
4. Use the 16-character password (not your regular password)

### SMS Gateway Setup
Common SMS gateway formats:
- **Verizon**: `number@vtext.com`
- **AT&T**: `number@txt.att.net`
- **T-Mobile**: `number@tmomail.net`
- **Sprint**: `number@messaging.sprintpcs.com`

## 🌐 Traefik Integration

### Docker Compose Labels
```yaml
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.webhook.rule=Host(`webhook.yourdomain.com`)"
  - "traefik.http.routers.webhook.entrypoints=websecure"
  - "traefik.http.routers.webhook.tls.certresolver=letsencrypt"
  - "traefik.http.services.webhook.loadbalancer.server.port=5000"
  
  # Security middleware
  - "traefik.http.routers.webhook.middlewares=webhook-headers,webhook-ratelimit"
  
  # Rate limiting
  - "traefik.http.middlewares.webhook-ratelimit.ratelimit.average=10"
  - "traefik.http.middlewares.webhook-ratelimit.ratelimit.burst=20"
```

### External Network