Event Specification
Canonical reference for the eight built-in event categories — purpose, common fields, and ordering constraints.
This page is the canonical reference for event modeling at the macro/base level.
Built-in logical event categories
| Type | Purpose |
|---|---|
ACTOR | Grants or updates participant roles/permissions on a document timeline. |
CLOSE | Closes the document for future updates (except specific relation flows). |
CANCEL | Cancels the document and blocks future actions. |
RELATED | Creates relation links between documents. |
UPDATE | Updates selected document visibility-related fields. |
SPLIT | Creates a new document with part of existing value. |
OUTPUT | Creates downstream document output from current context. |
CUSTOM | Methodology/application-specific event names. |
For implementation patterns using specific event categories, see:
ACTOR: Permissions guideCANCEL/CLOSE: Error Handling guideRELATED/SPLIT/OUTPUT: Submitting a MassIDUPDATE: Privacy & Masking guideCUSTOM: Defined per methodology — see the methodology integration guides for specific events and validation rules.
Common event fields
Most event payloads share these core fields:
nameexternalCreatedAtisPublicmetadata- one of
participantorparticipantId(required) - one of
addressoraddressId(required) - optional
attachments - optional
deduplicationId
For methodology-driven integrations, ACTOR events must include a label that identifies the participant role. Each methodology integration guide defines its allowed labels and required order. Do not use deprecated role fields such as actor-type.
CUSTOM events
CUSTOM events accept any event name — Network Integrators can define and send whatever operational events fit their workflow. The platform does not restrict CUSTOM event names at the API level.
Methodologies define their own expected CUSTOM event vocabularies and validate them through application rules. See the relevant methodology integration guide for the specific events and validation rules that apply.
Ordering and propagation constraints
- Event timestamps must remain chronologically consistent.
- Propagation behavior is constrained and should be explicitly validated in integration tests.
- Use deterministic retry patterns to avoid duplicate timeline entries.
Endpoint reference: Events API.