Realtime API

The Realtime API provides WebSocket-based pub/sub channels for real-time messaging between clients, with support for database change notifications, custom events, and webhook integrations.

Base URL

All realtime management endpoints are prefixed with /api/realtime

WebSocket URL

Connect to: wss://your-app.region.insforge.app/realtime

Channel Management

List All Channels

curl https://your-app.region.insforge.app/api/realtime/channels \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Retrieve all configured realtime channels. Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "pattern": "order:*",
    "description": "Order updates channel",
    "webhookUrls": ["https://example.com/webhook"],
    "enabled": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "pattern": "chat:*",
    "description": "Chat room messages",
    "webhookUrls": null,
    "enabled": true,
    "createdAt": "2024-01-16T11:00:00Z",
    "updatedAt": "2024-01-16T11:00:00Z"
  }
]

Create Channel

curl -X POST https://your-app.region.insforge.app/api/realtime/channels \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "order:*",
    "description": "Order updates channel",
    "webhookUrls": ["https://example.com/webhook"],
    "enabled": true
  }'

Create a new realtime channel with pattern-based subscription matching. Body Parameters

pattern

string

required

Channel pattern supporting wildcards (e.g., “order:”, “chat:room:”)

description

string

Human-readable description

webhookUrls

array

URLs to receive webhook notifications for channel messages

enabled

boolean

default:"true"

Whether channel is active

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "pattern": "order:*",
  "description": "Order updates channel",
  "webhookUrls": ["https://example.com/webhook"],
  "enabled": true,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Get Channel by ID

curl https://your-app.region.insforge.app/api/realtime/channels/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Retrieve specific channel details. Path Parameters

string

required

Channel UUID

Update Channel

curl -X PUT https://your-app.region.insforge.app/api/realtime/channels/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated order channel description",
    "enabled": false
  }'

Update channel configuration. Path Parameters

string

required

Channel UUID

Body Parameters

pattern

string

Updated channel pattern

description

string

Updated description

webhookUrls

array

Updated webhook URLs

enabled

boolean

Updated enabled status

Delete Channel

curl -X DELETE https://your-app.region.insforge.app/api/realtime/channels/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Delete channel and all associated subscriptions. Path Parameters

string

required

Channel UUID

Message History

List Messages

curl "https://your-app.region.insforge.app/api/realtime/messages?channelId=550e8400-e29b-41d4-a716-446655440000&limit=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Retrieve message history with filtering. Query Parameters

channelId

string

Filter by channel UUID

eventName

string

Filter by event name

limit

integer

default:"100"

Maximum messages to return (1-1000)

offset

integer

default:"0"

Number of messages to skip

Response

[
  {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "eventName": "order.created",
    "channelId": "550e8400-e29b-41d4-a716-446655440000",
    "channelName": "order:123",
    "payload": {
      "orderId": "123",
      "status": "pending",
      "total": 99.99
    },
    "senderType": "user",
    "senderId": "770e8400-e29b-41d4-a716-446655440000",
    "wsAudienceCount": 5,
    "whAudienceCount": 1,
    "whDeliveredCount": 1,
    "createdAt": "2024-01-15T10:30:00Z"
  }
]

Get Message Statistics

curl "https://your-app.region.insforge.app/api/realtime/messages/stats?since=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get aggregated message statistics. Query Parameters

channelId

string

Filter by channel UUID

since

string

Filter since timestamp (ISO 8601)

Response

{
  "totalMessages": 1250,
  "whDeliveryRate": 0.98,
  "topEvents": [
    {
      "eventName": "order.created",
      "count": 450
    },
    {
      "eventName": "order.updated",
      "count": 380
    },
    {
      "eventName": "order.completed",
      "count": 220
    }
  ]
}

WebSocket Connection

Connect to WebSocket

const ws = new WebSocket('wss://your-app.region.insforge.app/realtime');

ws.onopen = () => {
  console.log('Connected to realtime server');
  
  // Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'YOUR_ACCESS_TOKEN'
  }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Disconnected from realtime server');
};

Authentication

Send authentication message immediately after connection:

{
  "type": "auth",
  "token": "YOUR_ACCESS_TOKEN"
}

Response:

Success

{
  "type": "auth_success",
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Error

{
  "type": "error",
  "message": "Invalid token"
}

ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'order:123'
}));

Message Format:

{
  "type": "subscribe",
  "channel": "order:123"
}

Response:

Success

{
  "type": "subscribed",
  "channel": "order:123",
  "subscriptionId": "abc123"
}

Error

{
  "type": "error",
  "message": "Channel not found or not accessible"
}

Unsubscribe from Channel

ws.send(JSON.stringify({
  type: 'unsubscribe',
  channel: 'order:123'
}));

Message Format:

{
  "type": "unsubscribe",
  "channel": "order:123"
}

Response:

{
  "type": "unsubscribed",
  "channel": "order:123"
}

Publish Message

ws.send(JSON.stringify({
  type: 'publish',
  channel: 'order:123',
  event: 'order.updated',
  payload: {
    orderId: '123',
    status: 'shipped',
    trackingNumber: 'TRACK123'
  }
}));

Message Format:

{
  "type": "publish",
  "channel": "order:123",
  "event": "order.updated",
  "payload": {
    "orderId": "123",
    "status": "shipped"
  }
}

Response:

Success

{
  "type": "published",
  "messageId": "660e8400-e29b-41d4-a716-446655440000",
  "channel": "order:123",
  "event": "order.updated"
}

Receive Messages

Subscribed clients receive messages in this format:

{
  "type": "message",
  "messageId": "660e8400-e29b-41d4-a716-446655440000",
  "channel": "order:123",
  "event": "order.updated",
  "payload": {
    "orderId": "123",
    "status": "shipped",
    "trackingNumber": "TRACK123"
  },
  "senderId": "770e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00Z"
}

Database Change Notifications

ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'db:posts',
  filter: {
    event: 'INSERT',  // INSERT, UPDATE, DELETE, or *
    schema: 'public'
  }
}));

Received Change Notification:

INSERT Event

{
  "type": "message",
  "channel": "db:posts",
  "event": "INSERT",
  "payload": {
    "schema": "public",
    "table": "posts",
    "commit_timestamp": "2024-01-15T10:30:00Z",
    "eventType": "INSERT",
    "new": {
      "id": "248373e1-0aea-45ce-8844-5ef259203749",
      "title": "New Post",
      "content": "Hello world",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    "old": null
  }
}

UPDATE Event

{
  "type": "message",
  "channel": "db:posts",
  "event": "UPDATE",
  "payload": {
    "schema": "public",
    "table": "posts",
    "eventType": "UPDATE",
    "old": {
      "id": "248373e1-0aea-45ce-8844-5ef259203749",
      "title": "Old Title"
    },
    "new": {
      "id": "248373e1-0aea-45ce-8844-5ef259203749",
      "title": "Updated Title"
    }
  }
}

DELETE Event

{
  "type": "message",
  "channel": "db:posts",
  "event": "DELETE",
  "payload": {
    "schema": "public",
    "table": "posts",
    "eventType": "DELETE",
    "old": {
      "id": "248373e1-0aea-45ce-8844-5ef259203749",
      "title": "Deleted Post"
    },
    "new": null
  }
}

Permissions

Get Realtime Permissions

curl https://your-app.region.insforge.app/api/realtime/permissions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Retrieve RLS policies for subscribe and publish operations. Response

{
  "subscribe": {
    "policies": [
      {
        "policyName": "allow_authenticated_subscribe",
        "tableName": "realtime_channels",
        "command": "SELECT",
        "roles": ["authenticated"],
        "using": "enabled = true",
        "withCheck": null
      }
    ]
  },
  "publish": {
    "policies": [
      {
        "policyName": "allow_authenticated_publish",
        "tableName": "realtime_messages",
        "command": "INSERT",
        "roles": ["authenticated"],
        "using": null,
        "withCheck": "true"
      }
    ]
  }
}

Webhook Integration

When messages are published to channels with configured webhook URLs, InsForge sends HTTP POST requests: Webhook Payload:

{
  "messageId": "660e8400-e29b-41d4-a716-446655440000",
  "channelId": "550e8400-e29b-41d4-a716-446655440000",
  "channelName": "order:123",
  "event": "order.updated",
  "payload": {
    "orderId": "123",
    "status": "shipped"
  },
  "senderId": "770e8400-e29b-41d4-a716-446655440000",
  "senderType": "user",
  "timestamp": "2024-01-15T10:30:00Z"
}

Headers:

Content-Type: application/json
X-InsForge-Event: order.updated
X-InsForge-Channel: order:123
X-InsForge-Message-ID: 660e8400-e29b-41d4-a716-446655440000

Core APIs

Management APIs

Base URL

WebSocket URL

Channel Management

List All Channels

Create Channel

Get Channel by ID

Update Channel

Delete Channel

Message History

List Messages

Get Message Statistics

WebSocket Connection

Connect to WebSocket

Authentication

Unsubscribe from Channel

Publish Message

Receive Messages

Database Change Notifications

Permissions

Get Realtime Permissions

Webhook Integration

Core APIs

Management APIs

Documentation Index

​Base URL

​WebSocket URL

​Channel Management

​List All Channels

​Create Channel

​Get Channel by ID

​Update Channel

​Delete Channel

​Message History

​List Messages

​Get Message Statistics

​WebSocket Connection

​Connect to WebSocket

​Authentication

​Subscribe to Channel

​Unsubscribe from Channel

​Publish Message

​Receive Messages

​Database Change Notifications

​Subscribe to Table Changes

​Permissions

​Get Realtime Permissions

​Webhook Integration

Base URL

WebSocket URL

Channel Management

List All Channels

Create Channel

Get Channel by ID

Update Channel

Delete Channel

Message History

List Messages

Get Message Statistics

WebSocket Connection

Connect to WebSocket

Authentication

Subscribe to Channel

Unsubscribe from Channel

Publish Message

Receive Messages

Database Change Notifications

Subscribe to Table Changes

Permissions

Get Realtime Permissions

Webhook Integration