Events

Events are immutable log entries attached to entities. They represent things that happened: a player depositing funds, placing a bet, or starting a session. Events are append-only: once recorded, they cannot be modified.

Record an event

POST /operator-data-api/entities/:externalId/events

Request

Field	Type	Required	Description
eventType	string	Yes	Event type as defined in your template
data	object	Yes	Event payload, must include all required fields for this event type

Event types (iGaming template)

Event Type	Description	Required Fields
transaction	Deposits, withdrawals, adjustments	type, amount, currency
game_activity	Bets, wins, game rounds	game_id, bet_amount
session	Logins, logouts, session tracking	None
bonus	Bonus awards, wagering, forfeitures	None
block	Self-exclusion, account restrictions	None
support	Support tickets, interactions	None
affiliate	Affiliate tracking, attribution	None

Event type format

Event types are top-level names only: transaction, game_activity, etc. Do not use dotted formats like transaction.deposit. The subtype goes in the data payload (e.g. "type": "deposit").

Idempotency

Include an Idempotency-Key header to prevent duplicate event recording. If an event with the same idempotency key already exists, the original event ID is returned with "action": "duplicate". Keys are scoped to your operator and expire after 24 hours.

Example: Record a deposit

curl -X POST https://api.onehazel.com/operator-data-api/entities/player_12345/events \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deposit-txn-abc123" \
  -d '{
    "eventType": "transaction",
    "data": {
      "type": "deposit",
      "amount": 100.00,
      "currency": "GBP",
      "method": "card",
      "provider": "stripe",
      "reference": "txn_abc123",
      "card_last4": "4242"
    }
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "eev_b2c3d4e5f6789012"
  }
}

Example: Record a game round

curl -X POST https://api.onehazel.com/operator-data-api/entities/player_12345/events \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "game_activity",
    "data": {
      "game_id": "european-roulette",
      "game_name": "European Roulette",
      "provider": "evolution",
      "bet_amount": 5.00,
      "win_amount": 12.50,
      "currency": "GBP",
      "round_id": "round_xyz789"
    }
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "eev_c3d4e5f678901234"
  }
}

Example: Record a session event

curl -X POST https://api.onehazel.com/operator-data-api/entities/player_12345/events \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "session",
    "data": {
      "action": "login",
      "ip_address": "203.0.113.42",
      "country": "GB",
      "device": "mobile",
      "browser": "Safari 17"
    }
  }'

List events

GET /operator-data-api/entities/:externalId/events

Returns events for an entity in reverse chronological order (newest first).

Query parameters

Parameter	Type	Default	Description
type	string	n/a	Filter by event type (e.g. transaction)
limit	integer	100	Number of events to return (max 100)
offset	integer	0	Pagination offset

Example

curl "https://api.onehazel.com/operator-data-api/entities/player_12345/events?type=transaction&limit=10" \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"

Response:

{
  "success": true,
  "data": [
    {
      "id": "eev_b2c3d4e5f6789012",
      "event_type": "transaction",
      "data": {
        "type": "deposit",
        "amount": 100.00,
        "currency": "GBP",
        "method": "card",
        "provider": "stripe",
        "reference": "txn_abc123"
      },
      "created_at": "2026-04-06T12:00:00.000Z"
    }
  ],
  "count": 1
}

Event fan-out

When an event is recorded, OneHazel emits an internal event of type entity_event.<eventType> (e.g. entity_event.transaction). This can trigger workflows, for example, "when a deposit occurs, call the KYC provider to run a check".

Error codes

HTTP Status	Error Code	Description
400	MISSING_FIELDS	eventType or data is missing
400	VALIDATION_FAILED	Data does not match template requirements
400	TEMPLATE_NOT_CONFIGURED	No template set. Call PUT /settings first
401	UNAUTHORIZED	Missing or invalid API key
404	ENTITY_NOT_FOUND	No entity with that externalId exists
429	RATE_LIMITED	Rate limit exceeded
500	INTERNAL_ERROR	Server error