# How to Handle Fastio Realtime Events with Node.js Express

Handle Fastio real-time file notifications in Node.js Express using WebSocket feeds and activity polling. Build reactive agent architectures without webhooks.
This guide covers prerequisites, Express server setup, WebSocket event streaming, local development, and production best practices.

Source: https://fast.io/resources/implement-fastio-webhooks-nodejs-express/
Last reviewed: 2026-02-24

## What Are Fastio Realtime Event Feeds?

Fastio provides a WebSocket events feed and a realtime activity feed that can be polled via the REST API at https://api.fast.io/current/. Instead of webhooks, your application connects directly to receive events when files are uploaded, modified, deleted, or shared.

Each payload includes an event object with details like event ID, event type, created timestamp, workspace ID, and file metadata.

Streaming events over WebSockets or polling the activity feed ensures your server stays reactive while remaining securely behind your firewall without exposing public endpoints.

Refer to the [Fastio documentation](https://fast.io) and REST API for payload schemas and activity polling endpoints.

## What to check before scaling Fastio event handling with Node.js Express

To handle Fastio real-time events with Node.js Express, prepare these prerequisites:

**Fastio Account:**
- Sign up for the [Fastio Business Trial](https://fast.io/pricing/) (14-day trial, card required).
- Create a workspace.
- Generate an API key from your account settings.

**Development Environment:**
- Node.js 18 or later.
- Project initialization:
```bash
mkdir fastio-events-express
cd fastio-events-express
npm init -y
npm install express ws dotenv axios
```

Create `.env`:
```env
FASTIO_API_KEY=your_actual_api_key_here
PORT=3000
```

## Connecting Fastio Realtime Feeds to Express Apps

Build a secure Express service that maintains an outbound WebSocket connection to Fastio's events stream.

Create `index.js`:
```javascript
const express = require('express');
const WebSocket = require('ws');
require('dotenv').config();

const app = express();
const port = process.env.PORT || 3000;
const apiKey = process.env.FASTIO_API_KEY;

app.use(express.json());

// Connect to Fastio WebSocket events feed
function connectEvents() {
  const ws = new WebSocket('wss://api.fast.io/current/events', {
    headers: { Authorization: `Bearer ${apiKey}` }
  });

ws.on('open', () => {
    console.log('Connected to Fastio events feed');
  });

ws.on('message', (data) => {
    try {
      const event = JSON.parse(data);
      console.log(`Event received: ${event.event_type} on ${event.resource?.name || 'resource'}`);
      // Route event to processing logic or AI agents
    } catch (err) {
      console.error('Error parsing event:', err);
    }
  });

ws.on('close', () => {
    console.log('Connection closed. Reconnecting in 5s...');
    setTimeout(connectEvents, 5000);
  });
}

connectEvents();

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(port, () => {
  console.log(`Express server running on port ${port}`);
});
```

This establishes an event listener without exposing public inbound webhook endpoints.

## Frequently asked questions

### How does Fastio stream real-time workspace events?

Fastio provides a WebSocket events feed for push streaming and a realtime activity feed via the REST API, avoiding the need for inbound webhooks.

### How do you listen to Fastio events in Node.js Express?

Use a WebSocket client like 'ws' inside your Node.js application to connect to Fastio's WebSocket events endpoint and handle incoming file notifications.

### Do I need ngrok to test Fastio events on localhost?

No. Because your Node.js application initiates an outbound connection to Fastio's WebSocket feed, you can test on localhost without using ngrok or opening firewall ports.

### How do I handle network interruptions?

Listen for the WebSocket 'close' event and reconnect with exponential backoff. You can query Fastio's activity feed to fetch any events that occurred while disconnected.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.