Subscriptions

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
File Upload / Ingestion Events: projectModelIngestionUpdated (see the example below), projectPendingVersionsUpdated (legacy)
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.

Tracking file upload and model ingestion progress

projectModelIngestionUpdated fires whenever a model ingestion — for example a file upload started with fileUploadMutations.startFileIngestion from the file upload guide — is created or changes status. The ingestionReference input takes exactly one of modelId (all ingestions targeting a model) or ingestionId (a single ingestion):

subscription OnModelIngestionUpdated {
  projectModelIngestionUpdated(
    input: { projectId: "your-project-id", ingestionReference: { modelId: "your-model-id" } }
  ) {
    type
    modelIngestion {
      id
      modelId
      statusData {
        ... on ModelIngestionQueuedStatus {
          status
          progressMessage
        }
        ... on ModelIngestionProcessingStatus {
          status
          progressMessage
          progress
        }
        ... on ModelIngestionSuccessStatus {
          status
          versionId
        }
        ... on ModelIngestionFailedStatus {
          status
          errorReason
        }
        ... on ModelIngestionCancelledStatus {
          status
          cancellationMessage
        }
        ... on ModelIngestionInvalidStatus {
          status
          validationMessage
        }
      }
    }
  }
}

The type field tells you what happened to the ingestion (created, updated, cancellationRequested, or deleted), and statusData is a union — use inline fragments as above to read the status-specific fields.

The projectPendingVersionsUpdated subscription still works, but it reports file uploads through the legacy pending-version surface. Use projectModelIngestionUpdated for new integrations — it covers all ingestion types and carries granular status and progress data.

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:

Feature	Subscriptions	Webhooks
Connection Type	WebSocket (persistent)	HTTP POST (stateless)
Best For	Client applications, real-time UI	Server-to-server, CI/CD, automation
Connection Management	Requires active connection	No connection needed
Scalability	Limited by WebSocket connections	Scales with HTTP endpoints
Setup Complexity	Requires WebSocket client	Simple HTTP endpoint

GraphQL

REST

Webhooks

Guides

Overview

Available Subscriptions

Using Subscriptions

Endpoint and Authentication

Example

Tracking file upload and model ingestion progress

Connection Management

Comparison with Webhooks

​Overview

​Available Subscriptions

​Using Subscriptions

​Endpoint and Authentication

​Example

​Tracking file upload and model ingestion progress

​Connection Management

​Comparison with Webhooks

Overview

Available Subscriptions

Using Subscriptions

Endpoint and Authentication

Example

Tracking file upload and model ingestion progress

Connection Management

Comparison with Webhooks