Skip to main content

Real-Time Websocket Quickstart

This quickstart pulls together the minimum you need to start receiving real-time Legalesign GraphQL events.

info

If you prefer server-to-server callbacks over persistent connections, webhooks are also available (described in the REST API section).

Using an AI coding assistant?

For best results, give your AI tool these pages together:

You will:

  • get an access token
  • open an AppSync websocket connection
  • subscribe to a user or group feed
  • parse the event envelope
  • route on category and event

Before You Start​

You need:

  • API access enabled for your account
  • a Legalesign user account
  • an access token
  • a groupId if you want to use subscribeGroupFeed

Start here if you have not done those steps yet:

Step 1: Choose a Feed​

Use:

  • subscribeUserFeed for user-targeted events such as upload progress
  • subscribeGroupFeed for group-targeted events such as document, recipient, template, task, credit, and lifecycle updates

User feed​

subscription SubscribeUserFeed {
  subscribeUserFeed {
    userId
    data
  }
}

Group feed​

subscription SubscribeGroupFeed($groupId: String!) {
  subscribeGroupFeed(groupId: $groupId) {
    groupId
    data
  }
}

Step 2: Connect to the Websocket Endpoint​

Use the AppSync websocket endpoint:

wss://graphql.uk.legalesign.com/graphql

Pass your bearer token in the connection parameters.

import { createClient } from 'graphql-ws';
import WebSocket from 'ws';

const client = createClient({
  url: 'wss://graphql.uk.legalesign.com/graphql',
  webSocketImpl: WebSocket,
  connectionParams: {
    Authorization: `Bearer ${accessToken}`,
  },
});

Step 3: Subscribe​

client.subscribe(
  {
    query: `
      subscription SubscribeGroupFeed($groupId: String!) {
        subscribeGroupFeed(groupId: $groupId) {
          groupId
          data
        }
      }
    `,
    variables: {
      groupId: '<your-group-id>',
    },
  },
  {
    next: ({ data }) => {
      console.log('raw message', data);
    },
    error: console.error,
    complete: () => console.log('subscription closed'),
  }
);

Step 4: Parse the Inner Payload​

The subscription field returns:

  • a delivery wrapper (groupId or userId)
  • a JSON string in data

Parse the inner data field before doing anything else:

const parseEnvelope = (payload) => {
  const raw = payload?.data;
  if (!raw) return null;
  return typeof raw === 'string' ? JSON.parse(raw) : raw;
};

Example:

next: ({ data }) => {
  const wrapper = data?.subscribeGroupFeed;
  const event = parseEnvelope(wrapper);

  console.log('event id', event?.eventId);
  console.log('category', event?.category);
  console.log('event', event?.event);
  console.log('payload', event?.data);
}

Step 5: Route on category and event​

Do not build new integrations around legacy systemMessage-style codes.

Use:

  • category to identify the event family
  • event to identify the specific change

Examples:

  • category: "upload", event: "uploadCompleted"
  • category: "task", event: "taskCompleted"
  • category: "documentLifecycle", event: "documentCreated"
  • category: "recipientLifecycle", event: "recipientVisiting"

Typical Starting Patterns​

If you are choosing where to start:

Export This Article

Save a copy of this page as PDF or plain text.