Using Subscriptions

Subscriptions are useful for real-time UX such as:

• upload progress
• async task progress
• document and recipient lifecycle updates
• credit changes

For the payload schema itself, see:

• Connect to AppSync Subscriptions
• Subscription Event Format
• Subscription Event Schema

Parse the Inner Event Payload

The subscription field returns:

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

Always parse the inner data value before handling the event.

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

Route by category and event

Treat:

• category as the event family
• event as the specific action or workflow state

Examples:

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

Delivery Rules

• subscribeUserFeed is used for user-targeted events such as upload progress and some lifecycle fanout.
• subscribeGroupFeed is used for group-targeted events such as document, recipient, template, task, credit, and lifecycle updates.
• Some events are fanned out to both feeds with the same eventId.

Compatibility Guidance

If you are migrating from the older flat subscription payloads:

• parse the inner data envelope first
• move event routing to event instead of legacy systemMessage
• use category to decide how to interpret data
• continue ignoring unknown data fields

Representative Event Names

Common event names include:

• documentArchived
• documentCancelled
• recipientUpdated
• recipientReset
• documentCreated
• documentFinalPdfCreated
• documentRejected
• recipientSentEmail
• recipientVisiting
• recipientCompleted
• recipientRejected
• recipientEmailOpened
• taskDocumentCreated
• taskCompleted
• taskStoppedByRecipientStopList
• taskTrialCreditBlocked
• taskCreditBlocked
• templateArchived
• templateUpdated
• templateElementCreated
• templateElementUpdated
• templateElementDeleted
• templateRoleCreated
• templateRoleUpdated
• templateRoleDeleted
• uploadScanned
• uploadTypeChecked
• uploadConverting
• uploadFlattened
• uploadTagsParsed
• uploadPdfMetaExtracted
• uploadCompleted
• uploadFailed
• creditUpdated

Dedicated workflow guides:

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