InsuredAuditDeveloper Portal

Event Envelope

The Universal Event Envelope is the wire format for every record on the ledger. Source of truth: packages/canonical-events/src/envelope.ts (Zod schema). The OpenAPI spec mirrors that schema as components.schemas.EventEnvelope.

Required fields

{
  "event_family":            "claim",                    // one of EVENT_FAMILIES
  "event_type":              "CLAIM_SUBMITTED",
  "tenant_id":               "acme",
  "member_id":               "01HZZMEMBERID...",
  "source_system":           "EDI_CLAIMS_GW",
  "source_record_type":      "x12_837",
  "source_record_id":        "GW-2026-05-23-000123",
  "event_effective_timestamp": "2026-05-23T12:00:00Z",
  "payload":                 { "claim_amount_cents": 24500 }
}

Time model (BR-004)

Three timestamps are tracked separately and never collapsed:

  • source_event_timestamp — when the source system says the event happened. Optional.
  • event_effective_timestamp — when the event takes effect per the domain (e.g. a coverage start date). Required.
  • event_observed_timestamp — when the platform first saw the event. Optional; the server stamps it on ingest if absent.

Provenance (BR-003)

Every envelope must identify the source system + record sufficient to recover the original artifact: source_system + source_record_type + source_record_id together act as a stable natural key. source_event_id is optional but recommended when the source emits its own per-event ID.

Correlation

Optional fields for graph linkage:

  • correlation_id, causation_id — generic tracing IDs.
  • parent_event_id — the prior event in a workflow chain.
  • related_*_ids arrays — bind an envelope to claims, authorizations, prescriptions, disputes, documents, and rules. Each array caps at 256 IDs.

Outcome + classification

  • outcome + outcome_reason — domain-specific enums (APPROVED, DENIED, etc.).
  • data_classification — e.g. PHI, PII, PUBLIC.
  • legal_hold_status, retention_policy_id — overrides for retention sweeps.

Payload

payload is a free-form JSON object. The envelope only guarantees it’s an object; per-event_type payload schemas live in packages/canonical-events/src/payloads/and are validated by domain modules downstream, not at the envelope boundary.

Hashing + chaining

On commit the server computes envelope_hash as SHA-256 over the canonical JSON serialization of the envelope. Hashes are chained per (tenant_id, source_system) partition by setting prev_event_hash to the previous envelope’s hash. The full envelope bytes are also persisted to the WORM store; see WORM storage.