Streams

The Streams module provides real-time event collection, schema enforcement, transformations, and forwarding for Zeotap. It offers a Segment-compatible API that lets you collect customer behavioral data from any source — web, mobile, or server-side — and route it to your data warehouse and downstream destinations.

What Are Events?

Events capture what customers do — page views, button clicks, purchases, sign-ups, and any other action you want to track. Unlike traits (which describe who a customer is), events describe customer behavior over time.

Each event contains:

• Event name — What happened (e.g., purchase_completed, page_viewed)
• Timestamp — When it happened
• User identifier — Who did it (user ID, anonymous ID, or both)
• Properties — Additional context (e.g., product_name, price, page_url)

Event Types

Zeotap supports four event types, matching the Segment specification:

How Events Flow Through Zeotap

1. Collection — Events arrive via the HTTP API using event sources for authentication
2. Validation — Event contracts enforce schemas, checking property types and required fields
3. Transformation — Event transformations modify events in-flight (rename, enrich, filter)
4. Forwarding — Event forwarding routes events to downstream destinations in real time
5. Warehouse writing — The event warehouse writer persists all events to your data warehouse for analysis
6. Consent filtering — Consent management automatically filters events based on user consent state

Key Features

Segment-Compatible API

The events API is fully compatible with the Segment spec. If you’re already using Segment’s analytics.js or server-side libraries, you can point them at Zeotap’s events endpoint with minimal code changes. See Sending Events for the full API format and examples.

Event Contracts

Define schemas for your events to ensure data quality. Contracts specify required and optional properties, data types, and what happens when events violate the schema. See Event Contracts.

Real-Time Transformations

Modify events as they flow through the system — rename events, add or remove properties, enrich with external data, or filter events entirely. See Event Transformations.

Forwarding to Destinations

Route events to downstream tools in real time. Configure per-event-type rules, property mapping, batching behavior, and retry logic. See Event Forwarding.

Consent-Aware Collection

Automatically filter events based on user consent preferences. Define consent categories (analytics, marketing, advertising) and Zeotap enforces them at collection time. See Consent Management.

Warehouse Persistence

Every event is written to your data warehouse for long-term storage and analysis. Tables are automatically created and schemas evolve as new properties appear. See Event Warehouse.

Real-Time Debugging

The event debugger provides a live stream of incoming events with schema validation results, property inspection, and delivery status to forwarding destinations.

API Reference

Events are sent to a dedicated stream host, separate from the control-plane API used to manage warehouses, models and syncs. Its base URL — written here as $EVENTS_BASE_URL — is shown alongside your event source keys in Events > Event Sources.

# Unified endpoint — event type comes from the body's "type" field
POST $EVENTS_BASE_URL/v1/events
 
# Per-type endpoints
POST $EVENTS_BASE_URL/v1/track
POST $EVENTS_BASE_URL/v1/identify
POST $EVENTS_BASE_URL/v1/page
POST $EVENTS_BASE_URL/v1/screen
POST $EVENTS_BASE_URL/v1/group
 
# Many events in one request
POST $EVENTS_BASE_URL/v1/batch
 
# Required headers
X-Write-Key: <event source key>
Content-Type: application/json

The event source key identifies the workspace, so these calls carry no Authorization or X-Workspace-ID header. The key may also be sent as the username in HTTP Basic auth with an empty password, or as a ?writeKey= query parameter. See Sending Events for the request format and Event Sources for key management.

Throughput

Ingest does not apply a per-source events-per-second cap, so no request is rejected for arriving too fast. Throughput is still worth designing for:

• Batch where you can. /v1/batch accepts many events in one request, which is far more efficient than one request per event for server-side and mobile sources.
• Keep bodies within the limits. A single-event request body is capped at 1 MB and a batch at 10 MB. Split a large batch across requests rather than growing one past the limit — an oversized body is read up to the cap and then fails to parse, surfacing as 400 Bad Request.
• Expect asynchronous delivery. A 200 means the event was accepted, not that it has reached your warehouse or your forwarding destinations. Those happen downstream on their own schedule.

If you are planning an unusually large migration or backfill, talk to your account team first so capacity can be checked ahead of the load.

Best Practices

• Use consistent event naming — Adopt a naming convention like object_action (e.g., product_viewed, cart_updated, order_completed) and enforce it with event contracts
• Include meaningful properties — Add context that will be useful for analysis and segmentation, but avoid PII in event properties when possible
• Use a separate event source per source — Create separate event sources for each app, site or service so volume stays attributable and revoking one key affects one integration
• Enable contracts early — Define event contracts before you start collecting data to prevent schema drift
• Monitor with the debugger — Use the event debugger during development and after deploying new tracking to verify events arrive correctly

Next Steps

• Event Sources — Create and manage authentication keys for event sources
• Sending events — API format, event types, and code examples
• Event contracts — Enforce data quality with schema validation
• Debugging — Real-time event stream viewer and troubleshooting tools