Events Overview

Understand how the Atlas event tracking system works — event types, domains, and the ingestion pipeline.

What is Event Tracking?

Event tracking is how your platform communicates with Atlas. Every meaningful player action — placing a bet, making a deposit, creating an account — is an event that you send to Atlas in real-time.

Atlas processes these events to power your analytics, risk management, compliance monitoring, and behavioral insights.

Event Domains

Atlas organizes events into four domains, each with a dedicated endpoint:

Users

register · update

Player lifecycle events: account creation and profile changes.

Transactions

deposit · withdraw

Financial events: money in and money out.

Casino

open · win · lose

Casino game events: slots, table games, live casino rounds.

Sports

open · win · lose · cashout

Sports betting lifecycle from placement to settlement.

Generic vs Domain Events

You have two options for sending events:

	Domain Events	Generic Events
Endpoint	/api/v1/{domain}	/v1/events
Validation	Schema-validated per domain	Flexible — any JSON payload
Analytics	Full, pre-built analytics	Custom analytics only
Auth	API Key	JWT Bearer
Recommended	Yes, for known event types	For custom/internal events

Use domain events whenever possible. They give you pre-built analytics, risk scoring, and compliance monitoring out of the box.

How Events Flow

Your Backend
    │
    │  POST /api/v1/sport
    │  { event: "open", bet_id: "...", selections: [...] }
    ▼
Events API
    │ Validate + Enrich
    ▼
Kafka Topic
(atlas.events.raw.sportsbook)
    │
    ├──► Financial Engine ──► GGR / Revenue Reports
    ├──► Risk Engine      ──► Exposure / Alerts
    ├──► Player Profile   ──► Behavior Analytics
    └──► Compliance       ──► AML Monitoring

Response Model

Every successful event ingestion returns 202 Accepted — meaning the event was received and published to Kafka. Processing is asynchronous.

{
  "data": {
    "bet_id": "bet_abc_001"
  }
}

202 Accepted means the event reached Kafka, not that it was fully processed. Keep your domain IDs (bet_id, transaction_id, user_id) in logs for easier traceability.

Batch vs Single Events

For high-volume scenarios, always use batch endpoints:

Mode	Endpoint	Max Events	Best For
Single	POST /api/v1/sport	1	Real-time, latency-sensitive
Batch	POST /api/v1/sport/batch	500	High-volume, background jobs

→ See the Batch Ingestion Guide for patterns and examples.

Required Fields

All domain events share these required fields:

Field	Type	Description
org_id	string	Your organization ID
brand_id	string	The brand where the event occurred
event	string	The specific event (e.g., open)

Timestamps

Always include event timestamps in the domain payload (registered_at, transaction_dt, bet_dt). Atlas uses them for:

• Accurate time-series analytics
• Correct ordering of events
• Compliance audit trails

Use ISO 8601 format in UTC, e.g. "2026-03-11T14:30:00Z".

If your system generates events in bulk (e.g., settling bets after a game), use the actual event time in fields like bet_dt / transaction_dt / registered_at rather than current time. This ensures analytics reflect reality, not ingestion time.