evidencija-rezija/mailgun-webhook

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.

Quick Start

1. Installation

# Install dependencies
npm install

# Create environment file
cp .env.example .env
# Edit .env if needed (defaults work for development)

2. Development

# Start development server with hot reload
npm start

# Server will be running at http://localhost:3000

3. Testing the Webhook

# 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

# 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

# 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

Docker Deployment

Building the Docker Image

# Build the image
./build-image.sh 1.0.0

# The image will be tagged as mailgun-webhook-service:1.0.0

Running with Docker

# 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 - Complete API specification

License

ISC