GraphQL Subscription (WebSocket)

This page explains how to connect to the Rewards GraphQL API WebSocket for real-time updates

The Rewards GraphQL API provides a single WebSocket subscription (StatusUpdate) that delivers real-time notifications for:
  1. XP and level changes
  2. Virtual currency balance updates
  3. Wheel token grants and usage
  4. Challenge progress and completion
  5. Bonus awards
All updates are user-scoped and require authentication.

Connection Setup

Endpoint

Protocol

The WebSocket uses the graphql-ws protocol (also known as graphql-transport-ws). This is the modern GraphQL over WebSocket protocol, NOT the legacy subscriptions-transport-ws protocol.
When establishing the connection, the client must:
  1. Upgrade the HTTP connection to WebSocket
  2. Send a connection_init message with authentication parameters
  3. Wait for connection_ack before subscribing

Authentication

Authentication happens during the WebSocket handshake via the connectionParams (sent in the connection_init message).
Required parameters:
ParameterTypeDescription
connection_id
string
Required. A unique identifier for this connection (e.g., UUID). Used to track multiple connections per user.
Authorization
string
Recommended. JWT Bearer token (e.g., Bearer eyJhbGci...).
You must provide Authorization. The Authorization header with a JWT is the preferred method.
JWT Token Requirements:
  1. Must be a valid JWT signed with the configured secret (RSA or HMAC)
  2. Must contain user identity claims
  3. Token expiration is validated

Connection Parameters

Subscribing to Updates

Once connected and authenticated, subscribe to the StatusUpdate subscription:
GraphQL Subscription:
Response Format:
FieldTypeDescription
Type
string
The type of update (see Event Types)
Timestamp
string
ISO 8601 timestamp when the update occurred
UserID
int
The user ID this update belongs to
Data
string
JSON-encoded payload with update details

Handling Disconnects

WebSocket connections can be interrupted for various reasons:
  1. Network issues
  2. Server restarts
  3. Token expiration
  4. Idle timeout

Recommended Reconnection Strategy

Implement exponential backoff with jitter:

Connection State Management

Track connection states and handle transitions:
  1. Connecting - Initial connection attempt
  2. Connected - Received connection_ack
  3. Subscribed - Subscription active, receiving events
  4. Disconnected - Connection lost, should attempt reconnect
  5. Error - Authentication failed or unrecoverable error