Hash Chain

How It Works

Every event in Immutable is linked to the previous event in a per-workspace SHA-256 hash chain. This creates a tamper-evident seal across your entire audit trail — if any event is modified, inserted, or deleted at the database level, the chain breaks and the tampering is detectable.

Event 1              Event 2              Event 3
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│ data        │      │ data        │      │ data        │
│ prev: null  │─────>│ prev: h1    │─────>│ prev: h2    │
│ hash: h1    │      │ hash: h2    │      │ hash: h3    │
└─────────────┘      └─────────────┘      └─────────────┘

The first event in a workspace has previous_event_hash set to null.

Hash Computation

Each event hash is a SHA-256 digest computed from all event fields:

Field Group	Fields
Identity	`workspace_id`
Actor	`actor_id`, `actor_name`, `actor_type`
Action	`action`, `action_category`
Resource	`resource_id`, `resource_name`, `resource`
Context	`metadata`, `targets`, `occurred_at`
Network	`ip_address`, `ip_country`, `ip_city`, `user_agent`
Tracking	`tenant_id`, `session_id`, `idempotency_key`, `version`
Chain	`previous_event_hash`

Metadata keys are recursively sorted and targets are sorted by type then id before hashing. This ensures deterministic hashes regardless of JSON key order or array ordering in the database.

Chain Ordering

Events are chained by created_at (server-side timestamp with microsecond precision), not occurred_at (client-provided time). This guarantees a consistent, linear chain even when clients report out-of-order timestamps.

Concurrency Safety

Immutable uses PostgreSQL advisory locks (pg_advisory_xact_lock scoped by workspace ID via crc32) to ensure concurrent event ingestion does not produce conflicting hash chains. Only one event per workspace is hashed at a time.

Integrity Block

Every event returned by the API includes an integrity block:

{
  "integrity": {
    "event_hash": "a3f2c8d1e4b567890abcdef1234567890abcdef1234567890abcdef12345678",
    "previous_event_hash": "7b9e1d3f5a2c67890abcdef1234567890abcdef1234567890abcdef12345678"
  }
}

Verifying the Chain

Use the verify endpoint to validate the entire chain or a date range:

curl https://getimmutable.dev/api/v1/verify \
  -H "Authorization: Bearer imk_your_api_key_here"

{
  "data": {
    "valid": true,
    "events_checked": 4821,
    "breaks": []
  }
}

See Hash Verification for programmatic monitoring.

Break Types

If tampering is detected, the breaks array describes each issue:

Type	Description
`hash_mismatch`	The stored hash does not match the recomputed hash. The event data was modified.
`chain_break`	The `previous_event_hash` does not match the prior event’s hash. An event was inserted or deleted.

{
  "data": {
    "valid": false,
    "events_checked": 4821,
    "breaks": [
      {
        "event_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "type": "hash_mismatch",
        "expected_hash": "a3f2c8d1...",
        "actual_hash": "ff00ab12..."
      }
    ]
  }
}

Legacy events ingested before hash chain activation have nullable hash fields. The verify endpoint skips these events and does not report them as breaks.

Batch Event Ordering

When events are ingested via the batch endpoint, each event’s created_at is offset by 1 microsecond to preserve insertion order. Without this offset, batch events would share the same created_at value and UUID-based ordering would not match insertion order, causing false chain_break errors during verification.

Getting Started

Core Concepts

Platform Features

Security & Compliance

SDKs

Integration Guides

How It Works

Hash Computation

Chain Ordering

Concurrency Safety

Integrity Block

Verifying the Chain

Break Types

Batch Event Ordering

​How It Works

​Hash Computation

​Chain Ordering

​Concurrency Safety

​Integrity Block

​Verifying the Chain

​Break Types

​Batch Event Ordering

How It Works

Hash Computation

Chain Ordering

Concurrency Safety

Integrity Block

Verifying the Chain

Break Types

Batch Event Ordering