SSE Server API Documentation

This is a lightweight Server-Sent Events (SSE) server designed to facilitate real-time communication between your backend (e.g., n8n workflows) and your frontend applications.

Getting Started

Register for an account (the first registered user becomes the Admin automatically).
Navigate to your Dashboard and generate a new API Key.

1. Connect to the Event Stream (Frontend)

To receive real-time updates on your frontend, connect to the /events endpoint using the browser's native EventSource API.

Endpoint: GET /api/v1/events

Query Parameters:

channel (optional): The channel name you want to subscribe to. Defaults to global. This is useful if you want to segment events per user or per app.

Example (Vanilla JavaScript):

// Connect to a specific channel
const eventSource = new EventSource('https://your-server-url.onrender.com/api/v1/events?channel=user_123');

// Listen for a specific event type (e.g., 'workflow_update')
eventSource.addEventListener('workflow_update', (event) => {
  const data = JSON.parse(event.data);
  console.log('Received data:', data);
  // Update your progress bar or UI here
});

// Listen for the initial connection success event
eventSource.addEventListener('connected', (event) => {
  console.log(event.data);
});

// Handle errors
eventSource.onerror = (error) => {
  console.error('SSE Error:', error);
  // EventSource will automatically attempt to reconnect
};

2. Broadcast an Event (Backend / n8n)

To trigger an update on the frontend, your backend (e.g., an n8n webhook node) needs to send a POST request to this server.

Endpoint: POST /api/v1/broadcast

Headers:

Content-Type: application/json
x-api-key: sk_YOUR_GENERATED_API_KEY_HERE (Required for security)

Request Body (JSON):

Field	Type	Required	Description
`channel`	string	No	The channel to broadcast to. Defaults to `global`.
`event`	string	No	The name of the event. Useful for listening to specific event types on the frontend. Defaults to `message`.
`data`	object/string	Yes	The payload you want to send to the frontend.

Example payload:

{
  "channel": "user_123",
  "event": "workflow_update",
  "data": {
    "status": "processing",
    "progress": 45,
    "message": "Generating PDF..."
  }
}

Example cURL command:

curl -X POST https://your-server-url.onrender.com/api/v1/broadcast \
-H "Content-Type: application/json" \
-H "x-api-key: sk_your_generated_api_key_here" \
-d '{"channel": "user_123", "event": "workflow_update", "data": {"progress": 100, "status": "done"}}'

Rate Limiting & Security

Global Rate Limiting: IPs are limited to 100 requests per 15 minutes across all endpoints (excluding SSE connection durations).
Connection Rate Limiting: The /events endpoint allows a maximum of 30 connection attempts per minute per IP to prevent DDoS attacks.
Authentication: The /broadcast endpoint is protected by the x-api-key header.

Render Keep-Alive Mechanism

Render's free tier spins down servers after 15 minutes of inactivity. This server includes an internal self-pinging mechanism that calls its own /ping endpoint every 10 minutes.