Skip to main content

Hash Verification

Every definition version stores a SHA-256 hash of its source content (source_hash). This hash lets you prove — without privileged database access — that a specific file is byte-for-byte identical to what Stateway stored and executed.

Source hash in definition responses​

source_hash is included in all definition responses:

curl https://api.stateway.io/v1/definitions/credit-approval/versions/3 \
  -H "X-API-Key: sw_live_your_key"
{
  "data": {
    "id": "def_01j...",
    "key": "credit-approval",
    "version": 3,
    "sourceType": "bpmn",
    "source_hash": "a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "name": "Credit Approval",
    "createdAt": "2026-05-19T10:00:00Z"
  }
}

Verify a definition file​

The verify endpoint returns the hash and step-by-step verification instructions for any definition version:

curl https://api.stateway.io/v1/definitions/credit-approval/versions/3/verify \
  -H "X-API-Key: sw_live_your_key"
{
  "data": {
    "key": "credit-approval",
    "version": 3,
    "source_hash": "a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "algorithm": "sha256",
    "how_to_verify": "Run: sha256sum <your-file.bpmn> and compare with source_hash above"
  }
}

To verify a file on your machine:

sha256sum credit-approval-v3.bpmn
# a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2  credit-approval-v3.bpmn

If the output matches source_hash, the file is identical to what Stateway stored.

note

The hash is computed over the raw source bytes with no normalization. Any whitespace or encoding difference — including a trailing newline — will produce a different hash.

Definition hash in instance responses​

When a process instance is created, Stateway records the source_hash of the definition at that moment as definitionHash. This field and definitionId (the UUID of the definition record) appear in all instance responses:

{
  "data": {
    "id": "inst_01j...",
    "definitionId": "def-01j...",
    "definitionHash": "a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "status": "running",
    "startedAt": "2026-05-19T10:05:00Z"
  }
}

This lets you record the exact definition that was active when an instance started and verify it later — independent of any subsequent definition updates.

Verify an instance's definition​

The instance verify endpoint compares the definition_hash recorded at instantiation against the current hash of the same definition version:

curl https://api.stateway.io/v1/instances/inst_01j.../verify \
  -H "X-API-Key: sw_live_your_key"
{
  "data": {
    "instance_id": "inst_01j...",
    "definition_key": "credit-approval",
    "definition_version": 3,
    "definition_hash": "a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "current_definition_hash": "a3f1c2d4e5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
    "hash_match": true,
    "algorithm": "sha256"
  }
}
FieldDescription
definition_hashHash captured when the instance was created
current_definition_hashHash of the definition at the same version right now
hash_matchtrue if both hashes are equal

hash_match: false means the definition's stored content changed after the instance started. Because definitions are immutable, this should never occur in normal operation.