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 type | Chronological order | Deduplication | Timestamp extraction |
|---|---|---|---|
| UUID v4 | No | Yes (unique) | No |
| UUID v7 | Yes (millisecond) | Yes (unique) | Yes (48-bit ms) |
| ULID | Yes (millisecond) | Yes (unique) | Yes |
| Integer sequence | Yes | Yes | No |
Further reading
- Idempotency Key — Preventing Duplicate Operations
- UUID v7 for Audit Logging
- UUID v7 in Distributed Systems
- UUID v4 vs UUID v7
- Fencing Token
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.