CDP Event Envelope Schema for Kafka messages

cdp-event-envelope.md

CDP Event Envelope Schema

This is the JSON structure for all events published to Kafka topics (events.raw, events.views).

Structure

{
  "metadata": {
    "event_id": "uuid-v7",
    "event_type": "post.view",
    "version": "1.0",
    "timestamp": "2026-01-22T15:30:00.000Z"
  },
  "identity": {
    "tenant_id": 1,
    "user_ulid": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "device_uuid": "device-123",
    "session_uuid": "session-456"
  },
  "context": {
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0..."
  },
  "payload": {
    // Event-specific data (varies by event_type)
  }
}

Field Descriptions

metadata

Field	Type	Description
event_id	string	UUID v7 (time-ordered)
event_type	string	Event name (e.g., post.view, follow.create)
version	string	Schema version (currently 1.0)
timestamp	string	ISO 8601 timestamp

identity

Field	Type	Description
tenant_id	int	1=Parler, 2=PlayTV
user_ulid	string|null	Authenticated user's ULID
device_uuid	string|null	From X-Device-UUID header
session_uuid	string|null	Session ID (if available)

context

Field	Type	Description
ip_address	string|null	Client IP address
user_agent	string|null	Browser/app user agent

payload

Event-specific data. Examples:

post.view:

{
  "post_ids": [123, 456],
  "viewed_at": "2026-01-22T15:30:00.000Z"
}

video.progress:

{
  "percentage": 50,
  "duration_seconds": 120,
  "video_id": "vid-789"
}

Topics

Topic	Events	Volume
events.views	post.view, video.view, profile.view, stream.view	High
events.raw	All other events	Medium

ClickHouse Queries

JSONExtractString(raw, 'metadata', 'event_id') AS event_id,
JSONExtractString(raw, 'metadata', 'event_type') AS event_type,
JSONExtractInt(raw, 'identity', 'tenant_id') AS tenant_id,
JSONExtractString(raw, 'identity', 'user_ulid') AS user_ulid,
JSONExtractRaw(raw, 'payload') AS payload