Subscription Event Format

For the canonical AI-friendly schema reference, see Subscription Event Schema.

GraphQL subscriptions return a thin delivery wrapper and a JSON-encoded event envelope.

Delivery Wrapper

User feed responses look like:

{
  "data": "{\"version\":\"1.0\",\"eventId\":\"evt...\",\"timestamp\":\"2026-04-24T10:38:36.822Z\",\"level\":\"INFO\",\"event\":\"recipientVisiting\",\"category\":\"recipientLifecycle\",\"groupId\":\"grp...\",\"userId\":\"usr...\",\"requestId\":null,\"batchId\":null,\"error\":null,\"data\":{\"id\":\"rec...\",\"documentId\":\"doc...\",\"documentName\":\"Example document\",\"firstName\":\"Ada\",\"lastName\":\"Lovelace\"}}",
  "userId": "..."
}

Group feed responses use groupId instead of userId in the outer wrapper.

The wrapper identifies the subscription channel. The inner data string is the canonical event payload.

Event Envelope

After parsing data, you receive:

{
  "version": "1.0",
  "eventId": "evt...",
  "timestamp": "2026-04-24T10:38:36.822Z",
  "level": "INFO",
  "event": "recipientVisiting",
  "category": "recipientLifecycle",
  "groupId": "grp...",
  "userId": "usr...",
  "requestId": null,
  "batchId": null,
  "error": null,
  "data": {
    "id": "rec...",
    "documentId": "doc...",
    "documentName": "Example document",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }
}

Envelope Fields

Field	Description
version	Event envelope version. Currently 1.0.
eventId	Stable logical event ID. Fanout copies of the same event share the same value.
timestamp	ISO-8601 event timestamp.
level	Event severity. Currently usually INFO.
event	Canonical event name such as documentArchived or uploadCompleted.
category	Event family. This describes how to interpret data.
groupId	Group context when applicable.
userId	User context when applicable.
requestId	Request correlation ID when available.
batchId	Batch context when available.
error	Error payload when applicable, otherwise null.
data	Category-specific payload.

Categories

Current categories:

• document
• recipient
• documentLifecycle
• recipientLifecycle
• template
• task
• upload
• credit

category tells you what object or workflow the event is about. event tells you what happened.

Data Shapes

data is category-specific and forward-extensible:

• Producers may add fields over time.
• Producers should not remove existing fields incompatibly.
• Consumers should ignore fields they do not recognise.

Current base shapes:

// document
{ "id": "doc..." }

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

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

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

// template
{ "id": "tpl..." }

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

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

// credit
{ "credit": 172 }

Richer lifecycle data is currently populated most consistently for documentLifecycle and recipientLifecycle events.