Subscription Event Schema

This page is the canonical reference for Legalesign GraphQL subscription payloads.

Use it as the source of truth for:

• client implementations
• integration middleware
• AI assistants that need to reason about subscription events

For AI coding assistants

If you are using an AI coding tool to build subscription handling, give it these pages together:

• this schema reference
• Connect to AppSync Subscriptions
• Using Subscriptions

Then add the workflow-specific guide you need:

• Track Upload Progress with Subscriptions
• Track Send Tasks with Subscriptions
• Track Document and Recipient Lifecycle with Subscriptions

Delivery Wrapper

GraphQL subscriptions return a thin wrapper plus a JSON-encoded event payload in data.

User Feed

{
  "userId": "usr...",
  "data": "{\"version\":\"1.0\",\"eventId\":\"evt...\",\"timestamp\":\"2026-04-24T10:38:36.822Z\",\"level\":\"INFO\",\"event\":\"uploadCompleted\",\"category\":\"upload\",\"groupId\":null,\"userId\":\"usr...\",\"requestId\":null,\"batchId\":null,\"error\":null,\"data\":{\"id\":\"tmp...\",\"key\":\"upload/usr.../tmp....pdf\",\"code\":\"UPLOADOK\"}}"
}

Group Feed

{
  "groupId": "grp...",
  "data": "{\"version\":\"1.0\",\"eventId\":\"evt...\",\"timestamp\":\"2026-04-24T10:38:36.822Z\",\"level\":\"INFO\",\"event\":\"documentCreated\",\"category\":\"documentLifecycle\",\"groupId\":\"grp...\",\"userId\":\"usr...\",\"requestId\":null,\"batchId\":null,\"error\":null,\"data\":{\"id\":\"doc...\",\"documentName\":\"Example document\"}}"
}

Canonical Event Envelope

After parsing the wrapper data field, the event envelope is:

{
  "version": "1.0",
  "eventId": "evt...",
  "timestamp": "2026-04-24T10:38:36.822Z",
  "level": "INFO",
  "event": "documentCreated",
  "category": "documentLifecycle",
  "groupId": "grp...",
  "userId": "usr...",
  "requestId": null,
  "batchId": null,
  "error": null,
  "data": {}
}

Field Definitions

Field	Type	Required	Meaning
version	string	Yes	Envelope version. Currently 1.0.
eventId	string	Yes	Stable logical event ID. Same logical event may fan out to multiple feeds with the same eventId.
timestamp	string	Yes	ISO-8601 timestamp.
level	string	Yes	Event severity. Usually INFO.
event	string	Yes	Canonical event name.
category	string	Yes	Event family that defines how to interpret data.
groupId	string | null	No	Group context.
userId	string | null	No	User context or acting user.
requestId	string | null	No	Request correlation ID when available.
batchId	string | null	No	Batch context when available.
error	object | null	No	Error payload if the event carries one.
data	object	Yes	Category-specific payload.

Categories and Base Shapes

document

{
  "id": "doc..."
}

Thin document notification payload.

recipient

{
  "id": "rec...",
  "documentId": "doc..."
}

Thin recipient notification payload.

documentLifecycle

{
  "id": "doc...",
  "documentName": "Example document"
}

Used for richer document workflow/lifecycle events.

recipientLifecycle

{
  "id": "rec...",
  "documentId": "doc...",
  "documentName": "Example document",
  "firstName": "Ada",
  "lastName": "Lovelace"
}

Used for richer recipient workflow/lifecycle events.

template

Base shape for thin template notifications:

{
  "id": "tpl..."
}

Template editor events may expand this shape with:

{
  "id": "tpl...",
  "valid": true,
  "input": {}
}

task

{
  "id": "tsk...",
  "code": "TSKPROCESSOK",
  "documents": []
}

upload

{
  "id": "tmp...",
  "key": "upload/usr.../tmp....pdf",
  "code": "UPLOADOK"
}

credit

{
  "credit": 172
}

Event Families

Document

• documentArchived
• documentCancelled

Recipient

• recipientUpdated
• recipientReset

Document Lifecycle

• documentCreated
• documentFinalPdfCreated
• documentRejected

Recipient Lifecycle

• recipientSentEmail
• recipientVisiting
• recipientCompleted
• recipientRejected
• recipientEmailOpened

Task

• taskDocumentCreated
• taskCompleted
• taskStoppedByRecipientStopList
• taskTrialCreditBlocked
• taskCreditBlocked

Template

• templateArchived
• templateUpdated
• templateElementCreated
• templateElementUpdated
• templateElementDeleted
• templateRoleCreated
• templateRoleUpdated
• templateRoleDeleted

Upload

• uploadScanned
• uploadTypeChecked
• uploadConverting
• uploadFlattened
• uploadTagsParsed
• uploadPdfMetaExtracted
• uploadCompleted
• uploadFailed

Credit

• creditUpdated

Delivery Rules

• upload events are delivered on subscribeUserFeed.
• credit events are delivered on subscribeGroupFeed.
• document, recipient, template, task, documentLifecycle, and recipientLifecycle are typically delivered on subscribeGroupFeed.
• Some lifecycle events are fanned out to both user and group feeds.

Compatibility Rules

• Clients must parse the wrapper data string before consuming the event.
• Clients should route on category and event, not legacy systemMessage.
• data is forward-extensible. Producers may add fields over time.
• Consumers should ignore fields they do not recognise.
• Existing fields should not be removed or repurposed incompatibly.