RFC: Lead Dispatcher - Intelligent Lead Routing Platform

Status: Draft
Version: 1.0
Category: Technical Specification

---

Abstract

This document specifies a multi-tenant SaaS platform that receives leads via webhooks from marketplaces and e-commerce platforms, normalizes data into a fixed model, applies user-defined dynamic segmentation rules, and automatically routes leads to configured call centers. The system logs the entire distribution process and enables complete lifecycle tracking.

---

1. Terminology

Term	Definition
Lead	A potential customer record containing personal information, event data, and conversion details
Segment	A logical group defined by dynamic rules that leads can be assigned to
Dispatch	The process of sending a lead to a configured call center
Ruleset	A reusable set of rules that can be referenced across multiple segments
Tenant	An independent organization operating within the platform
Transformer	A platform-specific adapter that converts incoming payloads to the internal lead model
Target	A call center configured to receive leads from a specific segment

---

2. Project Overview

2.1 Objective

Build a multi-tenant SaaS platform that:

• Receives leads via webhooks from multiple marketplaces and e-commerce platforms
• Normalizes incoming data into a fixed internal model
• Applies dynamic user-defined segmentation rules
• Routes leads to configured call centers
• Logs the complete distribution process
• Enables full lifecycle tracking

2.2 Core Technologies

Layer	Technology
Frontend	Next.js + Zustand, Axios, Vite, Docker (Nginx)
Backend	NestJS (DDD + CQRS), MongoDB (Mongoose), JWT + RBAC, Docker
Infrastructure	EasyPanel (containers), MongoDB dedicated
Observability	Winston (logs), Sentry (errors), /health endpoint

---

3. Architecture and Flow

3.1 High-Level Flow

Marketplace/Platform
         │
         ▼
[Webhook Endpoint]
         │
         ▼
[Validation: HMAC + IP Allowlist]
         │
         ▼
[Normalization: Platform-specific transformer]
         │
         ▼
[Lead Creation/Update - Upsert by email]
         │
         ▼
[Rule Engine: Evaluate active segments]
         │
         ▼
[Identify New Segments - No re-dispatch to existing]
         │
         ▼
[Distribution: Weighted round-robin to targets]
         │
         ▼
[Send to Call Centers via HTTP POST]
         │
         ▼
[Log Dispatch Attempts]

3.2 Multi-Tenant Isolation

All data is isolated by orgId. Each organization operates independently with its own:

• Leads and conversions
• Segments and rules
• Call centers
• Users and permissions
• Webhook configurations

3.3 Webhook URL Pattern

https://api.example.com/hooks/{orgSlug}/{platform}/{event}/{slug}

Example: https://api.example.com/hooks/acme/cartpanda/ORDER_PAID/orders-paid

---

4. Functional Modules

4.1 Organization Management

Capabilities:

• Each organization has a unique slug used in webhook URLs
• Organizations are created only by PLATFORM_MASTER users
• Each tenant operates in complete isolation
• Default user role can be configured per organization

Creation Process:

• Organization name (required)
• Unique slug (required)
• Master user assignment (required)

4.2 User Management and RBAC

Available Roles

Role	Permissions
PLATFORM_MASTER	Global admin; creates/manages all organizations; full system access
ORG_MASTER	Organization owner; full control within org; manages users
ORG_ADMIN	Operational admin; manages call centers, segments, settings
ORG_OPERATOR	Basic operator; views and creates content; cannot delete or manage users

Role Hierarchy

PLATFORM_MASTER (Level 4)
    ↓
ORG_MASTER (Level 3)
    ↓
ORG_ADMIN (Level 2)
    ↓
ORG_OPERATOR (Level 1)

Permission Matrix

Action	PLATFORM_MASTER	ORG_MASTER	ORG_ADMIN	ORG_OPERATOR
Create organization	✅	❌	❌	❌
View all orgs	✅	❌	❌	❌
Switch org	✅	❌	❌	❌
Create user	✅	✅	✅	❌
Edit user	✅	✅	✅	❌
Delete ORG_MASTER	✅	❌	❌	❌
Delete ORG_ADMIN	✅	✅	❌	❌
Delete ORG_OPERATOR	✅	✅	✅	❌
Create content	✅	✅	✅	✅
Edit content	✅	✅	✅	✅
Delete content	✅	✅	✅	❌
View content	✅	✅	✅	✅
Configure webhooks	✅	✅	✅	✅
Rotate secret	✅	✅	✅	❌
Manage IP allowlist	✅	✅	✅	❌

Note: Content includes leads, segments, call centers, rulesets, and webhooks.

4.3 Webhook Module

Configuration Fields

Field	Description
Name	Human-readable identifier
Platform	Platform identifier (e.g., cartpanda, shopify)
Event	Event type (e.g., ORDER_PAID, ABANDONED_CART)
Slug	Unique identifier used in the URL
Secret	HMAC key for validation (optional)
IP Allowlist	List of allowed IPs (optional)

Security

HMAC Validation:

• If secret is configured, webhook must include X-Signature header
• Signature is HMAC SHA256 of the request body
• System validates before processing

IP Allowlist:

• Supports CIDR format (e.g., 203.0.113.0/24)
• Only listed IPs can send webhooks

Public Webhooks:

• No secret configured = publicly accessible
• IP allowlist still respected if configured

Supported Platforms

Platform	Events
CartPanda	ORDER_PAID, ORDER_REFUNDED, ORDER_CHARGEBACK, ABANDONED_CART, ORDER_UPSELL

Extensibility: Architecture supports adding new platform-specific transformers.

Secret Rotation

• Generate new random secret
• Maintain rotation history
• Old webhooks stop working immediately

4.4 Lead Module

Lead Structure

Basic Data:

• leadId: Unique identifier
• orgId: Owner organization
• email, firstName, lastName, phone, whatsapp
• geo: Country, state, city
• lang: Preferred language
• device: User device
• consent: GDPR/LGPD consent data

Event Data:

• eventId: Event type (e.g., ORDER_PAID)
• source: Origin (e.g., cartpanda)
• platformId: ID in source platform
• receivedAt: When received
• ingestedAt: When processed

Segmentation Data:

• segmentIds: List of assigned segments
• status: NEW, PROCESSED, DISPATCHED, etc.

Conversions:

• Array of conversion records (purchases, refunds, etc.)

Lead Creation Methods

1. Webhook - Automatic from marketplace data
2. CSV Import - Bulk upload
3. Manual Creation - Via API

CSV Import

Process:

1. Upload CSV file (max 20,000 rows)
2. Map columns to system fields
3. Preview data before import
4. System validates phone, email formats
5. Batch processing with error reporting

Mappable Fields:

• Standard: firstName, lastName, email, phone, whatsapp, age
• Nested: conversions.order, conversions.product
• Custom fields can be mapped dynamically

Search and Filters

• Name, email, phone
• Event type (ORDER_PAID, ABANDONED_CART, etc.)
• Status (NEW, PROCESSED, DISPATCHED)
• Associated segments
• Date range (receivedAt)
• Conversion fields (product, platform, etc.)

Statistics

• Total leads
• Leads by status
• Leads by source/platform
• Conversion rate
• Distribution by segment

Reprocessing

Leads can be reprocessed using a Redis queue with BullMQ jobs. This re-evaluates leads against segments and triggers new dispatches for matching segments.

4.5 Segment Module

Definition

Segments are groups of leads defined by dynamic rules. When a lead matches a segment's rules, it is automatically associated and sent to configured call centers.

Rule Criteria

• Purchased product
• Age range
• Geographic location
• UTM parameters (campaign, source, etc.)
• Purchase value
• Any combination of lead fields

Rule Operators

Operator	Description
eq	Equal to
ne	Not equal to
gt	Greater than
gte	Greater than or equal to
lt	Less than
lte	Less than or equal to
contains	String contains
regex	Regular expression
in	In list
not_in	Not in list

Logical Groups

• all: All conditions must be true (AND)
• any: At least one condition must be true (OR)
• Nested rules supported

Example Rule

{
  "all": [
    {
      "field": "conversions.productId",
      "op": "eq",
      "value": "PROD_123"
    },
    {
      "any": [
        { "field": "age", "op": "gte", "value": 25 },
        { "field": "age", "op": "lte", "value": 45 }
      ]
    },
    {
      "field": "geo.country",
      "op": "eq",
      "value": "BR"
    }
  ]
}

Interpretation: Product PROD_123 AND (age >= 25 OR age <= 45) AND country = BR

Targets

Each segment can have multiple call centers as destinations:

Field	Description
Call Center	Select from configured call centers
Weight	Distribution percentage
Rate Limit	Sends per minute for this target
Endpoint	Specific endpoint URL (optional)

Distribution: Weighted round-robin ensures proportional distribution.

Priority

Segments are evaluated in priority order (highest first). This enables:

• More specific segments evaluated first
• Generic segments as fallback
• Fine control over which segment "wins" when multiple apply

Simulator

• Test rules before activation
• Paste example lead data
• View result: "Matches" or "Does not match" with explanation

Preview

• View how many existing leads would match
• Sample up to 1000 leads
• Match count and coverage percentage

4.6 Call Center Module

Configuration Fields

Field	Description
Name	Human-readable identifier
Endpoints	URLs receiving leads (multiple per event type)
Secret	HMAC key for signing requests (optional)
Timeout	Max wait time for response (default: 5000ms)
Retries	Attempts on failure (default: 3)
Window	Operating hours
Daily Cap	Daily lead limit (default: 100)
Rate Limit	Per-minute limit (default: 120)
Active	Whether the call center is enabled

Endpoints by Event

Call centers can have different endpoints for different event types:

• order_paid: For paid orders
• abandoned_cart: For abandoned carts

System automatically selects the correct endpoint based on lead event type.

Operating Window

• Start/End times (HH:mm format)
• Timezone (e.g., America/Sao_Paulo)
• 24-hour operation option

Leads are only sent during the configured window.

Rate Limiting

Per Minute:

• Controls how many leads can be sent per minute
• Prevents call center overload

Daily Cap:

• Total leads per day
• Call center stops receiving when cap is reached

Payload Format

When a lead is sent, the call center receives JSON containing:

Lead Data:

• Personal information (name, email, phone)
• Geographic data
• Consent data

Segmentation Data:

• segmentId: Which segment triggered the dispatch
• segmentName: Segment name

Conversion Data:

• Product information
• Price
• Platform
• UTM parameters
• Billing and shipping addresses
• Order items

Metadata:

• receivedAt, ingestedAt: Timestamps
• callCenterAssignments: Other assigned call centers

Omitted Fields:

• leadId, orgId, eventId (internal only)

Endpoint Testing

• Send test payload
• Verify response
• Validate format and response time

4.7 Dispatch Module

Dispatch Process

1. Evaluation: System identifies matching segments for the lead
2. New Segments: Only segments the lead just entered (no re-dispatch to existing)
3. Distribution: For each new segment:
   • Fetch configured targets
   • Apply weights for distribution
   • Check rate limits and daily caps
   • Check operating windows
   • Send to each call center
4. Logging: Record every attempt

Dispatch Log

Field	Description
dispatchId	Unique dispatch identifier
leadId	Lead being sent
segmentId	Segment that triggered dispatch
callCenterId	Target call center
attempt	Attempt number (1, 2, 3...)
requestBody	Full payload sent
endpointName	Endpoint name (from call center config)
endpointPath	URL used
responseCode	HTTP status code
responseBody	Response body
status	SENT or FAILED
durationMs	Response time
timestamp	When sent

Automatic Retry

• System retries on failure
• Configurable retry count per call center
• Exponential backoff between attempts
• Each attempt is logged

4.8 Ruleset Module

Definition

Rulesets are reusable sets of rules that can be referenced across multiple segments.

Benefits

• Define a rule once, use in multiple segments
• Single point of update
• Consistency across segments

Example

Ruleset "Allowed Countries" with values ["BR", "US", "CA"] can be used in 10 different segments. Adding "MX" updates all segments at once.

Creation Fields

Field	Description
Name	Human-readable identifier
Description	Purpose explanation
Field	Lead field evaluated (e.g., geo.country)
Operator	IN or NOT_IN
Values	List of allowed/disallowed values

Status

A ruleset is "active" if used by at least one active segment. Status display helps identify unused rulesets for cleanup.

---

5. Data Schemas

Organization

{
  "id": "uuid",
  "name": "Organization Name",
  "slug": "acme",
  "defaultUserRole": "ORG_OPERATOR",
  "active": true,
  "createdAt": "ISO date",
  "updatedAt": "ISO date"
}

User

{
  "id": "uuid",
  "email": "user@example.com",
  "name": "John Doe",
  "passwordHash": "bcrypt_hash",
  "refreshToken": "bcrypt_hash",
  "active": true,
  "orgId": "uuid",
  "createdAt": "ISO date",
  "updatedAt": "ISO date"
}

Membership

{
  "id": "uuid",
  "orgId": "uuid",
  "userId": "uuid",
  "role": "ORG_MASTER | ORG_ADMIN | ORG_OPERATOR",
  "createdAt": "ISO date"
}

Lead

{
  "leadId": "uuid",
  "orgId": "uuid",
  "source": "cartpanda",
  "eventId": "ORDER_PAID",
  "receivedAt": "ISO date",
  "ingestedAt": "ISO date",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+5511999999999",
  "whatsapp": "+5511999999999",
  "consent": {
    "granted": true,
    "timestamp": "ISO date"
  },
  "geo": {
    "country": "BR",
    "state": "SP",
    "city": "Sao Paulo"
  },
  "lang": "pt-BR",
  "device": "desktop",
  "status": "NEW",
  "segmentIds": ["seg-123", "seg-456"],
  "callCenterAssignments": [
    {
      "callCenterId": "cc-123",
      "name": "Call Center A"
    }
  ],
  "conversions": [],
  "createdAt": "ISO date",
  "updatedAt": "ISO date"
}

Conversion

{
  "event": "ORDER_PAID",
  "platform": "cartpanda",
  "order": "12345",
  "product": "Product X",
  "productId": "PROD_456",
  "variant": "Variant Y",
  "price": 99.99,
  "source": "facebook",
  "shop": "Store ABC",
  "currency": "BRL",
  "utm": {
    "source": "facebook",
    "medium": "cpc",
    "campaign": "promo-january"
  },
  "billingAddress": {},
  "shippingAddress": {},
  "lineItems": [],
  "createdAt": "ISO date",
  "updatedAt": "ISO date"
}

Segment

{
  "segmentId": "uuid",
  "orgId": "uuid",
  "name": "Product X Leads: Age 25-45",
  "description": "Product X AND age between 25 and 45",
  "rules": {
    "all": [
      {
        "field": "conversions.productId",
        "op": "eq",
        "value": "PROD_123"
      },
      {
        "any": [
          { "field": "age", "op": "gte", "value": 25 },
          { "field": "age", "op": "lte", "value": 45 }
        ]
      }
    ]
  },
  "targets": [
    {
      "callCenterId": "cc-123",
      "weight": 70,
      "rateLimitPerMin": 60,
      "endpoint": "order_paid"
    },
    {
      "callCenterId": "cc-456",
      "weight": 30,
      "rateLimitPerMin": 40
    }
  ],
  "priority": 10,
  "active": true,
  "dispatchesCount": {
    "total": 14,
    "sent": 2,
    "failed": 12
  },
  "createdBy": "uuid",
  "createdAt": "ISO date",
  "updatedAt": "ISO date"
}

CallCenter

{
  "callCenterId": "uuid",
  "orgId": "uuid",
  "name": "Call Center A",
  "endpoint": [
    {
      "name": "order_paid",
      "url": ["https://cc-a.com/webhooks/order_paid"]
    },
    {
      "name": "abandoned_cart",
      "url": ["https://cc-a.com/webhooks/abandoned_cart"]
    }
  ],
  "secret": "HMAC-SECRET",
  "timeoutMs": 5000,
  "retries": 3,
  "window": {
    "start": "08:00",
    "end": "20:00",
    "tz": "America/Sao_Paulo",
    "is24h": false
  },
  "dailyCap": 100,
  "rateLimitPerMin": 120,
  "active": true,
  "dispatchesCount": {
    "total": 14,
    "sent": 2,
    "failed": 12
  },
  "format": "default",
  "createdBy": "uuid",
  "createdAt": "ISO date",
  "updatedAt": "ISO date"
}

DispatchLog

{
  "dispatchId": "uuid",
  "orgId": "uuid",
  "leadId": "uuid",
  "segmentId": "uuid",
  "callCenterId": "uuid",
  "attempt": 1,
  "requestBody": {},
  "responseCode": 200,
  "responseBody": {},
  "status": "SENT",
  "durationMs": 150,
  "timestamp": "ISO date",
  "endpointName": "order_paid",
  "endpointPath": "https://webhook.site.com/121212"
}

Dispatch Payload (Sent to Call Center)

{
  "receivedAt": "ISO date",
  "ingestedAt": "ISO date",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+5511999999999",
  "whatsapp": "+5511999999999",
  "consent": {
    "granted": true,
    "timestamp": "ISO date"
  },
  "geo": {
    "country": "BR",
    "state": "SP",
    "city": "Sao Paulo",
    "address": "Rua das Flores, 123"
  },
  "lang": "pt-BR",
  "device": "desktop",
  "status": "NEW",
  "segmentId": "seg-123",
  "segmentName": "Product X Leads",
  "callCenterAssignments": [
    {
      "callCenterId": "cc-123",
      "name": "Call Center A"
    }
  ],
  "conversion": {
    "event": "ORDER_PAID",
    "platform": "cartpanda",
    "order": "ORDER_123",
    "product": "Product X",
    "productId": "PROD_456",
    "variant": "Variant Y",
    "price": 99.99,
    "source": "facebook",
    "shop": "Store ABC",
    "currency": "BRL",
    "utm": {
      "source": "facebook",
      "medium": "cpc",
      "campaign": "promo-january"
    },
    "billingAddress": {},
    "shippingAddress": {},
    "lineItems": [],
    "subtotalPrice": 89.99,
    "totalDiscounts": 10.0,
    "totalTax": 5.0,
    "shippingPrice": 5.0,
    "createdAt": "ISO date",
    "updatedAt": "ISO date"
  },
  "createdAt": "ISO date",
  "timestamp": "ISO date"
}

Note: leadId, orgId, and eventId are omitted from dispatch payload. device is included only if present.

WebhookConfig

{
  "id": "uuid",
  "orgId": "uuid",
  "type": "incoming",
  "platform": "cartpanda",
  "event": "ORDER_PAID",
  "slug": "orders-paid",
  "name": "Orders Paid Webhook",
  "path": "/hooks/acme/cartpanda/ORDER_PAID/orders-paid",
  "secret": "HMAC-SECRET",
  "ipAllowlist": ["203.0.113.10"],
  "active": true,
  "createdAt": "ISO date",
  "updatedAt": "ISO date"
}

Ruleset

{
  "id": "uuid",
  "orgId": "uuid",
  "name": "Allowed Countries",
  "description": "Countries where we operate",
  "field": "geo.country",
  "defaultOperator": "IN",
  "values": ["BR", "US", "CA"],
  "createdAt": "ISO date",
  "updatedAt": "ISO date"
}

---

6. Key System Flows

6.1 Webhook to Dispatch Flow

1. Webhook Receipt: Marketplace POST to /hooks/{orgSlug}/{platform}/{event}/{slug}
2. Validation: HMAC verification and IP allowlist check
3. Identification: Organization identified by slug
4. Transformation: Platform-specific transformer converts payload
5. Normalization: Data normalized to internal lead model
6. Conversion Extraction: Product, price, UTM data extracted
7. Lead Creation/Update: Upsert by email; new lead gets NEW status
8. Segment Evaluation: All active segments evaluated in priority order
9. New Segment Identification: Compares current vs previous segments; only new segments trigger dispatch
10. Distribution: For each new segment:
    • Fetch targets
    • Apply weights
    • Check rate limits and daily caps
    • Check operating windows
    • Prepare payload
    • Send HTTP POST to each call center
11. Logging: Each attempt logged with full details

6.2 CSV Import Flow

1. Upload: User uploads CSV (max 20,000 rows)
2. Mapping: System auto-maps columns; user can adjust
3. Preview: Data preview with validation errors
4. Validation: Phone, email formats checked; duplicates identified
5. Processing: Batch processing with error reporting
6. Report: Import count, error list, downloadable report

6.3 Lead Reprocessing Flow

1. Selection: User selects leads by ID or filters
2. Cleanup: Existing segments cleared from lead
3. Re-evaluation: All active segments re-evaluated
4. Redistribution: All matching segments are "new" (after cleanup), triggering full dispatch

Use Cases:

• Segments were modified
• New call centers added
• Need to resend existing leads

---

7. Authentication and Security

7.1 JWT Authentication

Login:

• User provides email and password
• System validates credentials
• Returns access_token (15 min expiry) and refresh_token (7 days)

Refresh:

• Obtain new access token without re-login

Logout:

• Refresh token invalidated

7.2 RBAC Protection

All routes protected by guards that verify:

• Valid JWT token
• User role
• Organization context

7.3 Webhook Security

HMAC Validation:

• If secret configured, X-Signature header required
• Signature is HMAC SHA256 of request body
• Validated before processing

IP Allowlist:

• CIDR format supported
• Only listed IPs can send

Public Webhooks:

• No secret = public access
• IP allowlist still respected

7.4 Multi-Tenant Isolation

• All queries filter by orgId automatically
• Users only see their organization's data
• Cross-tenant data access impossible
• Organization context from JWT token

7.5 Data Security

Validation:

• All inputs validated with class-validator
• XSS and injection sanitization
• Type and format validation

Encryption:

• Passwords hashed with bcrypt
• JWT tokens signed
• HTTPS required in production

---

8. Observability

8.1 Logging

• Winston for structured logs
• Error, warn, info, debug levels
• Full operation context

8.2 Health Checks

• /health endpoint
• System and dependency status

8.3 Metrics

• Lead processing counters
• Dispatch statistics
• Performance metrics

---

9. Technology Stack Details

Component	Technology
Backend Framework	NestJS (TypeScript)
Database	MongoDB + Mongoose
Authentication	JWT + Passport
API Documentation	Swagger/OpenAPI
Validation	Class Validator
Frontend Framework	Next.js
State Management	Zustand
HTTP Client	Axios
Build Tool	Vite
Containerization	Docker
Container Management	EasyPanel
Logging	Winston
Error Tracking	Sentry

---

10. Development Guidelines

10.1 Environment Setup

git clone <repository-url>
npm install
cp .env.example .env
# Edit .env with configuration
npm run start:dev

10.2 Code Structure

src/
├── modules/
│   ├── auth/           # Authentication and org management
│   ├── leads/          # Lead management
│   ├── segments/       # Segmentation
│   ├── call-centers/   # Call center configuration
│   ├── dispatch/       # Distribution
│   ├── webhook/        # Webhook handling
│   └── rulesets/       # Reusable rules
├── main.ts             # Application bootstrap
├── app.module.ts       # Root module
└── swagger.ts          # Swagger configuration

Module Structure:

module/
├── application/
│   ├── controllers/    # HTTP endpoints
│   └── services/       # Business logic
├── domain/
│   ├── entities/       # Domain models
│   ├── dtos/           # Data Transfer Objects
│   └── repositories/   # Repository interfaces
└── infra/
    └── repositories/   # MongoDB implementations

10.3 Testing

npm test                 # All tests
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report
npm run test:e2e         # End-to-end tests

10.4 Adding New Webhook Platform

1. Create platform-specific transformer service
2. Implement transformOrderPaid() method
3. Implement extractConversionData() method
4. Add to PublicWebhookController routing
5. Add event mapping if needed

---

11. Operations Guide

11.1 Backup

• Configure regular MongoDB backups
• Use mongodump or managed backup services

11.2 Monitoring

• Monitor error logs regularly
• Configure alerts for critical errors
• Track lead volume and dispatch success rate
• Monitor processing latency

11.3 Scaling

Horizontal:

• Multiple instances supported
• MongoDB clustering available
• Load balancer in front of instances

Vertical:

• Increase CPU, RAM as needed
• MongoDB vertical scaling available

11.4 Common Troubleshooting

Issue	Checks
Webhook not receiving	Verify URL, secret, IP allowlist, error logs
Leads not dispatched	Check segment active, call center active, rate limits, dispatch logs
Slow performance	Check lead volume, resource usage, query optimization, indexes

---

12. Summary of Features

• Complete multi-tenancy with data isolation
• Webhook system for receiving leads from multiple platforms
• Dynamic segmentation with complex, combinable rules
• Automatic distribution to call centers with weights and limits
• Complete dispatch logs for traceability
• Bulk CSV lead import
• Robust RBAC with 4 permission levels
• Reusable rulesets for consistency
• Webhook security with HMAC and IP allowlist
• Manual lead reprocessing
• Advanced search and filters across all modules
• Interactive Swagger API documentation

---

13. Security Considerations

13.1 Authentication

• JWT tokens with short-lived access tokens (15 minutes)
• Refresh token rotation
• Secure token storage (HttpOnly cookies recommended)

13.2 Authorization

• RBAC enforcement at every endpoint
• Hierarchical permission model
• Context-aware authorization

13.3 Data Protection

• Field-level encryption for sensitive data
• PII masking in logs
• Audit trail for all operations

13.4 API Security

• Rate limiting per endpoint
• Input validation and sanitization
• CORS configuration
• HTTPS enforcement

---

14. References

• NestJS Documentation
• MongoDB Documentation
• JWT RFC 7519
• Swagger/OpenAPI Specification

---

Appendix A: Configuration Reference

Environment Variables

Variable	Description
MONGO_URI	MongoDB connection URI
JWT_ACCESS_SECRET	Access token signing secret
JWT_REFRESH_SECRET	Refresh token signing secret
PORT	Server port (default: 3000)
CORS_ORIGINS	Allowed CORS origins

---