Skip to main content

Auditing and Compliance

Stateway provides a complete, tamper-evident audit trail for every process execution. Every definition version, every gateway decision, every timer fire, and every decision rule evaluation is recorded and cryptographically linked.

The six mechanisms​

Definition fingerprinting​

Every process and decision definition stores a SHA-256 hash of its source content (source_hash). This hash appears in all definition responses and is immutable once set.

Use this to prove — without privileged database access — that a BPMN or DMN file you hold is identical to the version Stateway stored and executed. See Hash Verification.

Definition immutability​

Definitions are immutable after creation. Uploading new content via PUT /definitions/:key always creates a new version — it never modifies the source, hash, or parsed model of an existing version. A source_hash is a permanent fingerprint for a specific version.

Execution event trail​

Every element entry and exit, every gateway resolution, every timer fire, and every boundary event activation is written to the audit log under actorType: "engine". Gateway and boundary events include a variables_snapshot of the process variables at the exact moment the decision was made.

Use GET /instances/:id/history to retrieve the full event trail for a specific instance. See Audit Log.

Variable snapshots at decision points​

When the engine resolves a gateway or activates a boundary event, it captures the current process variables and stores them in the event payload as variables_snapshot. This snapshot is immutable and co-located with the event that triggered it.

This answers "what data caused the process to take this path?" with a durable, verifiable record.

Decision evaluation records​

Every DMN decision evaluation — whether called directly via the API or triggered by a businessRuleTask inside a running process — is persisted to a dedicated record. Each record includes the exact input variables, which rules matched, and the outputs produced.

Use GET /decisions/:key/evaluations to retrieve evaluation history. See Decision Trail.

Tamper-evident hash chain​

Each audit log entry includes an entryHash computed over its own content and the hash of the previous entry (prevEntryHash). Any deletion, insertion, or modification in the sequence produces a detectable mismatch.

Use GET /audit/verify to verify chain integrity over a time range. See Chain Integrity.

End-to-end compliance investigation​

A typical compliance workflow for a specific process instance:

  1. Retrieve the instance — GET /v1/instances/:id. Note definitionId and definitionHash.
  2. Verify the definition — GET /v1/instances/:id/verify. Confirms whether the definition changed after the instance was created (hash_match: true means it has not).
  3. Verify your local file — GET /v1/definitions/:key/versions/:v/verify. Compare the returned source_hash against sha256sum your-file.bpmn to confirm the file you hold matches the stored definition.
  4. Inspect the execution trail — GET /v1/instances/:id/history?actor_type=engine. See every step in execution order.
  5. Inspect gateway decisions — Add &action=gateway.resolved to the history query. Each event's payload.variables_snapshot shows the data available at the moment of the decision.
  6. Retrieve decision evaluations — GET /v1/decisions/:key/evaluations?instance_id=:id. See which rules matched for each decision made inside the process.
  7. Verify log integrity — GET /v1/audit/verify?from=<start>&to=<end>. Confirms no entries have been deleted or modified.