Skip to main content
The Speckle GraphQL API supports real-time subscriptions for receiving live updates about events such as new versions, comments, project changes, and more. Subscriptions use WebSocket connections and follow the GraphQL subscription specification.

​
Overview

GraphQL subscriptions provide a way to receive real-time updates from the Speckle server. Unlike webhooks, which are HTTP-based and designed for server-to-server communication, subscriptions are ideal for client applications that need to stay synchronized with Speckle data in real-time.
When to Use Subscriptions vs Webhooks:
  • Subscriptions: Use for client applications (web apps, desktop apps) that need real-time UI updates. Subscriptions use WebSocket connections and require an active connection.
  • Webhooks: Use for server-to-server integrations, CI/CD pipelines, and HTTP-based automation workflows. Webhooks send HTTP POST requests to your endpoint, making them ideal for serverless functions and webhook endpoints.
See the Webhooks documentation for HTTP-based event notifications and a complete comparison.

​
Available Subscriptions

The complete list of available subscriptions is documented in Apollo Studio: Apollo Studio - Subscriptions Common subscription types include:
  • Project Events: projectUpdated, projectModelsUpdated, projectVersionsUpdated, projectCommentsUpdated, projectIssuesUpdated
  • Version Events: projectVersionsUpdated, projectPendingVersionsUpdated
  • Automation Events: projectAutomationsUpdated, projectTriggeredAutomationsStatusUpdated
  • Workspace & User Events: workspaceUpdated, userProjectsUpdated
Legacy Subscriptions: Some subscriptions use legacy naming conventions (branch, commit, stream) for backward compatibility. These are marked with warnings in Apollo Studio. The modern equivalents use project, model, and version terminology.

​
Using Subscriptions

​
Endpoint and Authentication

Subscriptions use WebSocket connections. The endpoint for app.speckle.systems is: 
wss://app.speckle.systems/graphql
Authenticate using a personal access token in the connection parameters: 
import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
import { createClient } from 'graphql-ws';

const wsLink = new GraphQLWsLink(createClient({
  url: 'wss://app.speckle.systems/graphql',
  connectionParams: {
    Authorization: `Bearer ${YOUR_TOKEN}`
  }
}));

​
Example

Most subscriptions accept an id parameter to filter events for a specific project: 
subscription {
  projectVersionsUpdated(id: "your-project-id") {
    id
    modelId
    type
    version {
      id
      message
      createdAt
    }
  }
}
Some subscriptions, like userProjectsUpdated, don’t require parameters and will send updates for all projects the authenticated user has access to.

​
Connection Management

WebSocket connections may drop due to network issues. Implement reconnection logic with exponential backoff in your client. Unsubscribe from subscriptions when components unmount or are no longer needed.

​
Comparison with Webhooks

Both subscriptions and webhooks provide real-time event notifications, but they serve different use cases:
FeatureSubscriptionsWebhooks
Connection TypeWebSocket (persistent)HTTP POST (stateless)
Best ForClient applications, real-time UIServer-to-server, CI/CD, automation
Connection ManagementRequires active connectionNo connection needed
ScalabilityLimited by WebSocket connectionsScales with HTTP endpoints
Setup ComplexityRequires WebSocket clientSimple HTTP endpoint