Events

The Events module provides real-time event collection, schema enforcement, transformations, and forwarding for SignalSmith. 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

SignalSmith supports four event types, matching the Segment specification:

How Events Flow Through SignalSmith

1. Collection — Events arrive via the HTTP API using write keys 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 SignalSmith’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 SignalSmith 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 through the Events API:

# Events endpoint
POST /api/v1/events
 
# Required headers
Authorization: Basic <base64(write_key:)>
Content-Type: application/json

The write key is sent as the username in HTTP Basic auth with an empty password. See Write Keys for key management.

Rate Limits

Rate limits are applied per write key. Events exceeding the limit receive a 429 Too Many Requests response.

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 write keys per source — Create separate write keys for web, mobile, and server-side sources so you can manage permissions and rate limits independently
• 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

• Write keys — 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