Real-time Updates

Get instant notifications when jobs complete, fail, or move through the queue. Use WebSocket for bi-directional communication or SSE for simple one-way streaming.

When to use which:

WebSocket

Interactive dashboards, real-time UIs, bi-directional communication

SSE (Server-Sent Events)

Simple event streaming, CLI tools, backend services, simpler reconnection

How It Works

Spooled streams job events in real-time as they happen. Subscribe to specific queues or all events for your organization.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ecfdf5', 'primaryTextColor': '#065f46', 'primaryBorderColor': '#10b981', 'lineColor': '#6b7280'}}}%%
sequenceDiagram
  participant C as Client
  participant S as Spooled
  participant W as Worker
  
  C->>S: Connect WebSocket/SSE
  C->>S: Subscribe to queue events
  
  Note over W,S: Worker processes job
  W->>S: job.complete()
  S->>C: Event: job.completed
  
  W->>S: job.fail()
  S->>C: Event: job.failed

Event Types

Event	Description	Payload
`job.created`	New job queued	`{"type":"JobCreated","data":{...}}`
`job.status`	Job status changed	`{"type":"JobStatusChange","data":{...}}`
`job.completed`	Job finished successfully	`{"type":"JobCompleted","data":{...}}`
`job.failed`	Job failed (may retry)	`{"type":"JobFailed","data":{...}}`
`queue.stats`	Queue stats update	`{"type":"QueueStats","data":{...}}`
`worker.heartbeat`	Worker heartbeat	`{"type":"WorkerHeartbeat","data":{...}}`
`worker.registered`	Worker registered	`{"type":"WorkerRegistered","data":{...}}`
`worker.deregistered`	Worker deregistered	`{"type":"WorkerDeregistered","data":{...}}`
`system.health`	System health update	`{"type":"SystemHealth","data":{...}}`
`ping`	Connection keep-alive	`{"type":"Ping","data":{...}}`
`error`	Error event	`{"type":"Error","data":{...}}`

   Note: For SSE, the SSE event: name is one of
job.created, job.status, job.completed, job.failed,
queue.stats, etc. The SSE data: is a JSON object with {"type": "...", "data": {...}}.
 
 WebSocket
 
WebSocket provides a persistent, bi-directional connection. Use it for interactive applications
    that need to subscribe/unsubscribe to different topics.
 
# WebSocket connections require a WebSocket client.
# Example using websocat (install: https://github.com/vi/websocat)
#
# 1) Exchange API key for a JWT access token (requires jq)
TOKEN=$(curl -s -X POST https://api.spooled.cloud/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"api_key":"sp_live_YOUR_API_KEY"}' | jq -r .access_token)
  
# 2) Connect (token goes in the query string)
websocat "wss://api.spooled.cloud/api/v1/ws?token=$TOKEN"

# 3) Subscribe by sending JSON commands over the socket.
# (Tip: see the Node.js/Python SDK tabs for a ready-to-run subscription example.)
import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

// WebSocket realtime client (uses /api/v1/ws?token=... under the hood)
const realtime = await client.realtime({ type: 'websocket' });

realtime.on('job.created', (data) => {
  console.log('job.created:', data);
});

realtime.on('job.completed', (data) => {
  console.log('job.completed:', data);
});

await realtime.connect();
await realtime.subscribe({ queueName: 'orders' });
from spooled import SpooledClient
from spooled.realtime import SubscriptionFilter
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

# WebSocket realtime client (uses /api/v1/ws?token=... under the hood)
realtime = client.realtime(type="websocket")

@realtime.on("job.created")
def on_job_created(data):
    print("job.created:", data)

@realtime.on("job.completed")
def on_job_completed(data):
    print("job.completed:", data)

realtime.connect()
realtime.subscribe(SubscriptionFilter(queue="orders"))
import (
	"context"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/realtime"
)

client, _ := spooled.NewClient(spooled.WithAPIKey("sp_live_YOUR_API_KEY"))

ws := client.Realtime().WebSocket()

ws.OnEvent("job.created", func(data realtime.EventData) {
	fmt.Println("job.created:", data)
})

ws.OnEvent("job.completed", func(data realtime.EventData) {
	fmt.Println("job.completed:", data)
})

ws.Connect(context.Background())
ws.Subscribe(realtime.Filter{QueueName: "orders"})
<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

// WebSocket realtime client
$realtime = $client->realtime();

$realtime->ws()->onEvent('job.created', function (array $data): void {
    echo "job.created: " . json_encode($data) . "\n";
});

$realtime->ws()->onEvent('job.completed', function (array $data): void {
    echo "job.completed: " . json_encode($data) . "\n";
});

$realtime->ws()->connect();
$realtime->ws()->subscribe(['queueName' => 'orders']);
 WebSocket Protocol
 
Spooled Cloud authenticates realtime connections using a short-lived JWT token passed via the URL:
/api/v1/ws?token=.... The SDKs handle reconnect + subscribe for you.
 
If you implement the protocol manually, WebSocket commands are JSON messages like
{"cmd":"Subscribe","queue":"emails","job_id":null}.
    Prefer using the SDK unless you have a strong reason not to.
 Server-Sent Events (SSE)
 
SSE is simpler than WebSocket — just an HTTP request that streams events. Perfect for
    CLI tools, backend services, or when you don't need bi-directional communication.
 
# Stream events via Server-Sent Events
curl -N \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  "https://api.spooled.cloud/api/v1/events"

# Stream events for a specific queue
curl -N \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer sp_live_YOUR_API_KEY" \
  "https://api.spooled.cloud/api/v1/events/queues/my-queue"
import { SpooledClient } from '@spooled/sdk';

const client = new SpooledClient({
  apiKey: process.env.SPOOLED_API_KEY!,
});

// SSE realtime client (uses /api/v1/events with Authorization header under the hood)
const realtime = await client.realtime({ type: 'sse' });

realtime.on('job.created', (data) => {
  console.log('job.created:', data);
});

await realtime.connect();
await realtime.subscribe({ queueName: 'orders' });
from spooled import SpooledClient
from spooled.realtime import SubscriptionFilter
import os

client = SpooledClient(api_key=os.environ["SPOOLED_API_KEY"])

realtime = client.realtime(type="sse")

@realtime.on("job.created")
def on_job_created(data):
    print("job.created:", data)

realtime.connect()
realtime.subscribe(SubscriptionFilter(queue="orders"))
import (
	"context"
	"github.com/spooled-cloud/spooled-sdk-go/spooled"
	"github.com/spooled-cloud/spooled-sdk-go/spooled/realtime"
)

client, _ := spooled.NewClient(spooled.WithAPIKey("sp_live_YOUR_API_KEY"))

sse := client.Realtime().SSE()

sse.OnEvent("job.created", func(data realtime.EventData) {
	fmt.Println("job.created:", data)
})

sse.Connect(context.Background())
sse.Subscribe(realtime.Filter{QueueName: "orders"})
<?php

use Spooled\SpooledClient;
use Spooled\Config\ClientOptions;

$client = new SpooledClient(new ClientOptions(
    apiKey: getenv('SPOOLED_API_KEY'),
));

// SSE realtime client
$realtime = $client->realtime();

$realtime->sse()->subscribe(function (array $event): void {
    echo "Event: {$event['type']} - Job: {$event['data']['jobId']}\n";
});

$realtime->sse()->subscribeToQueue('orders', function (array $event): void {
    echo "Queue event: {$event['type']}\n";
});

$realtime->sse()->listen();
 SSE vs WebSocket
     Feature  WebSocket  SSE  
 
   Connection  Bi-directional  Server → Client only  
  Protocol  WebSocket (ws://wss://)  HTTP (http://https://)  
  Reconnection  Manual  Automatic (built-in)  
  Browser support  All modern browsers  All modern browsers  
  Firewall friendly  Sometimes blocked  Regular HTTP traffic  
  Best for  Interactive apps, dashboards  Simple streaming, CLI tools  
 
 
 
 gRPC Streaming
 
For the lowest latency and highest throughput, use gRPC bidirectional streaming.
    This is ideal for high-performance workers and backend services.
  gRPC Streaming
 
See the gRPC API documentation for streaming examples
      using StreamJobs and SubscribeEvents.
 
      
     Dashboard Tip 
   
📍 Dashboard (real-time)  
   
What to look for:
   → Live job status updates 
 → Queue throughput graphs 
 → Worker activity 
 
 
      
The Spooled dashboard itself uses WebSocket for real-time updates. You can use the same
      APIs to build your own monitoring tools.
  
 
 
 
 Best Practices
 Reconnection
 
Always implement reconnection logic. Network interruptions happen, and your application
    should automatically reconnect with exponential backoff.
 Event Ordering
 
Events for a single job are delivered in order. Events across different jobs may arrive
    out of order. Use job IDs and timestamps for correlation.
 Idempotent Handlers
 
Events may be delivered more than once during reconnection. Design your event handlers
    to be idempotent.
 Next Steps
  Jobs & queues — Understand job lifecycle events
 gRPC API — High-performance streaming
 SDKs — Real-time support in Node.js, Python, Go, and PHP

Feature	WebSocket	SSE
Connection	Bi-directional	Server → Client only
Protocol	WebSocket (ws://wss://)	HTTP (http://https://)
Reconnection	Manual	Automatic (built-in)
Browser support	All modern browsers	All modern browsers
Firewall friendly	Sometimes blocked	Regular HTTP traffic
Best for	Interactive apps, dashboards	Simple streaming, CLI tools