Event IDs are the backbone of event-driven architecture — they make events addressable, replayable, and deduplicated. UUID v7 embeds the event creation time, removing the need for a separate occurred_at timestamp in most event store schemas. See Idempotency Key for the deduplication pattern.

Domain event with UUID v7 ID

import { v7 as uuidv7 } from 'uuid';

interface DomainEvent {
  id:          string;  // UUID v7 — encodes event time
  type:        string;
  aggregateId: string;
  payload:     unknown;
}

function createEvent(type: string, aggregateId: string, payload: unknown): DomainEvent {
  return {
    id:          uuidv7(), // UUID v7 — creation time embedded, globally unique
    type,
    aggregateId,
    payload,
  };
}

const event = createEvent('OrderPlaced', orderId, { total: 99.99 });

Event store — PostgreSQL

CREATE TABLE events (
  id           UUID         PRIMARY KEY,  -- UUID v7
  aggregate_id UUID         NOT NULL,
  type         TEXT         NOT NULL,
  payload      JSONB        NOT NULL,
  INDEX idx_events_aggregate (aggregate_id, id)
);
// Append event to store
async function appendEvent(event: DomainEvent) {
  await pool.query(
    'INSERT INTO events (id, aggregate_id, type, payload) VALUES ($1, $2, $3, $4)',
    [event.id, event.aggregateId, event.type, JSON.stringify(event.payload)]
  );
}

// Replay events for an aggregate from a checkpoint
async function replayFrom(aggregateId: string, fromEventId?: string) {
  const { rows } = fromEventId
    ? await pool.query(
        'SELECT * FROM events WHERE aggregate_id = $1 AND id > $2 ORDER BY id',
        [aggregateId, fromEventId]
      )
    : await pool.query(
        'SELECT * FROM events WHERE aggregate_id = $1 ORDER BY id',
        [aggregateId]
      );
  return rows;
}

Time-range replay using UUID v7

// Replay all events since a given time — no occurred_at column
function uuidV7MinAt(date: Date): string {
  const ms  = BigInt(date.getTime());
  const hex = ms.toString(16).padStart(12, '0');
  return `${hex.slice(0,8)}-${hex.slice(8,12)}-7000-8000-000000000000`;
}

async function replayFromTime(since: Date) {
  const minId = uuidV7MinAt(since);
  const { rows } = await pool.query(
    'SELECT * FROM events WHERE id > $1 ORDER BY id',
    [minId]
  );
  return rows;
}

Deduplication with Redis

import { createClient } from 'redis';

const redis = createClient();

// Idempotent event processing — UUID v7 event ID as dedup key
async function processEvent(event: DomainEvent): Promise<boolean> {
  const key    = `event:seen:${event.id}`;
  const wasNew = await redis.set(key, '1', { NX: true, EX: 86400 });

  if (!wasNew) {
    console.log(`Duplicate event ${event.id} — skipped`);
    return false;
  }

  await handleEvent(event);
  return true;
}

Event ID ordering comparison

ID typeChronological orderDeduplicationTimestamp extraction
UUID v4NoYes (unique)No
UUID v7Yes (millisecond)Yes (unique)Yes (48-bit ms)
ULIDYes (millisecond)Yes (unique)Yes
Integer sequenceYesYesNo

Further reading

Frequently asked questions

What is an event ID in event-driven architecture?

An event ID is a unique identifier assigned to each event — a record that something happened (OrderPlaced, PaymentProcessed, UserSignedUp). Event IDs enable deduplication (consumers check if they have seen this ID before), ordering (sort by ID), and replay (re-process events from a specific ID onward). See Idempotency Key for the related deduplication pattern.

Why use UUID v7 as an event ID instead of a random UUID?

UUID v7 provides event creation time without a separate occurred_at field. This enables time-range replay (WHERE event_id > uuid_v7_at(checkpoint)), chronological ordering without timestamps, and audit queries that answer "what events occurred during this outage window" using a UUID range scan. See UUID v7 for Audit Logging.

How does UUID v7 event ID deduplication work?

Consumers store the event IDs they have processed in a deduplication set (Redis Set, database unique index). When a new event arrives, check: IF NOT EXISTS(event_id IN seen_ids) THEN process(event). UUID v7 is globally unique — no two independently generated UUIDs match, making false positives impossible. See Idempotency Key.