Copy page

Microservices

HTTP Server & Webhook Endpoint

HTTP Server & Webhook Endpoint

Relevant source files

The following files were used as context for generating this wiki page:

• emailsender/src/server/http-server.ts

The EmailSender microservice includes a lightweight HTTP server built using the native Node.js http module. This server serves two primary purposes: providing a health check mechanism for container orchestration (e.g., Docker, Kubernetes) and exposing a public webhook endpoint to receive delivery status notifications from external email providers like Brevo.

Server Implementation

The server is initialized via the createHttpServer function, which defaults to listening on port 3003 emailsender/src/server/http-server.ts:11-11. It avoids heavy framework dependencies like Express, opting for a direct implementation using createServer emailsender/src/server/http-server.ts:12-12.

Endpoint Overview

Path	Method	Purpose	Authentication
/health	GET	Service liveness check	None
/webhook	POST	Inbound provider events	API Key (Bearer/ApiKey)

Sources:

• emailsender/src/server/http-server.ts:11-64

---

Webhook Endpoint (/webhook)

The /webhook endpoint is the entry point for asynchronous updates from email providers. It identifies the source provider via a URL query parameter and routes the payload to the internal business logic.

Authentication Logic

The server enforces security by comparing the Authorization header against the WEBHOOK_API_KEY environment variable emailsender/src/server/http-server.ts:5-9. It supports both Bearer and ApiKey prefix formats emailsender/src/server/http-server.ts:18-25.

Request Processing Flow

1. URL Parsing: The server extracts the provider from the search parameters (defaulting to "brevo") emailsender/src/server/http-server.ts:28-28.
2. Stream Consumption: The request body is collected into Buffer chunks and parsed as JSON emailsender/src/server/http-server.ts:31-36.
3. Service Delegation: The parsed payload and provider ID are passed to the WebhookService.handleWebhook method emailsender/src/server/http-server.ts:38-38.

Data Flow: External Event to WebhookService

The following diagram illustrates how an external HTTP request is transformed into a call to the internal service layer.

Webhook Request Handling Flow

Code
sequenceDiagram
    participant P as "External Provider (e.g. Brevo)"
    participant S as "http.createServer (IncomingMessage)"
    participant H as "createHttpServer Logic"
    participant W as "WebhookService"

    P->>S: POST /webhook?provider=brevo
    Note over S: Headers: Authorization: Bearer <key>
    S->>H: Request Stream
    H->>H: Validate WEBHOOK_API_KEY
    alt Invalid Key
        H->>P: 401 Unauthorized
    else Valid Key
        H->>H: Buffer.concat(chunks)
        H->>H: JSON.parse(body)
        H->>W: handleWebhook("brevo", payload)
        W-->>H: Promise<void>
        H->>P: 200 OK
    end

Sources:

• emailsender/src/server/http-server.ts:12-48
• emailsender/src/services/webhook-service.ts:4-4 (Reference to WebhookService)

---

Health Check Endpoint (/health)

The /health endpoint provides a simple JSON response to indicate that the microservice process is running and the HTTP event loop is responsive.

• Response Body: {"status": "healthy"} emailsender/src/server/http-server.ts:53-53
• Content Type: application/json emailsender/src/server/http-server.ts:52-52

This endpoint is critical for the Docker HEALTHCHECK directive and orchestration readiness probes.

Sources:

• emailsender/src/server/http-server.ts:51-55

---

Integration and Data Mapping

The HTTP server acts as a bridge between the "External Network Space" and the "Internal Service Space." It maps raw HTTP primitives (Methods, Headers, Streams) to typed service calls.

Entity Mapping: HTTP to Code

Code
graph TD
    subgraph "External Network Space"
        R["HTTP POST /webhook"]
        A["Authorization Header"]
        Q["?provider=brevo"]
        B["JSON Body"]
    end

    subgraph "Code Entity Space (emailsender/src/server/http-server.ts)"
        F["createHttpServer"]
        K["webhookApiKey (Env Var)"]
        WS["WebhookService.handleWebhook"]
    end

    R --> F
    A -- "Extracted & Compared" --> K
    Q -- "provider string" --> WS
    B -- "parsed payload object" --> WS

Sources:

• emailsender/src/server/http-server.ts:1-64
• emailsender/src/services/webhook-service.ts:1-10

---

Error Handling & Reliability

• Startup Validation: If WEBHOOK_API_KEY is missing from the environment variables, the server will throw an error and prevent the microservice from starting emailsender/src/server/http-server.ts:7-9.
• Request Safety: The webhook handler is wrapped in a try/catch block. Any failure during body parsing or service execution results in a 500 Internal Server Error response to the provider, preventing the server process from crashing emailsender/src/server/http-server.ts:42-46.
• Default Routing: Any request that does not match /webhook or /health receives a 404 Not Found response emailsender/src/server/http-server.ts:57-58.

Sources:

• emailsender/src/server/http-server.ts:7-9
• emailsender/src/server/http-server.ts:42-48
• emailsender/src/server/http-server.ts:57-59

---