Event Stream

Introduction

The Event Stream enables your platform to send real-time player activity to Unibo. This data is required for campaign progression and real-time campaign processing.
By integrating with the Unibo Consumer service, your platform sends gameround and transaction events that are processed by Unibo as they occur.
Sending bet, win, and deposit events via the Event Feed is required for campaigns to function correctly. Player and game updates may be sent via the Event Stream or provided separately through the  Metadata  integration.


Events Processed by Unibo

The Unibo Consumer is designed to receive the following required events in real time:
  • Bets – when a player places a wager in a game
  • Wins – when a player receives a payout from a bet
  • Deposits – when a player deposits funds into their account
  • Login – when a player logs into their account. An optional event used for raffle campaigns only
In addition, Unibo may receive updates related to players and games through the Even Stream. These updates are used for campaign targeting and segmentation, but may also be provided via the metadata integration.


Technical Documentation

For the most up-to-date and detailed API documentation, please refer to the Unibo Consumer service directly at  https://consumer.unibo.io . The service provides interactive Swagger documentation and an OpenAPI specification ( openapi.json ).
The primary endpoint for sending events is:
POST /api/v1/events
This endpoint accepts batches of events in JSON format.


Event Model

Platforms differ in how game rounds are represented. Unibo supports both of the following approaches, and the exact approach is aligned during integration:
  • Single event per game round: one event including both the bet and the outcome (win amount).
  • Two events per game round: separate bet and win events, linked using a shared round_id (or equivalent game round identifier).
In both cases, each event must include a unique identifier (unique_id) and a timestamp representing when the event occurred.


Idempotency and Timestamps

To ensure accurate and reliable event processing, the following rules apply.

Idempotency

Each event must include a unique event identifier (unique_id). Events are deduplicated by Unibo using this identifier, allowing platforms to safely retry sending events or entire batches without risking duplicate processing.

Timestamps

Each event must include a timestamp indicating when it occurred. The timestamp must reflect the actual event time (for example, when the bet was placed), not when the event was sent. Accurate timestamps are required for campaign logic and latency monitoring.

Example Event

{
  "event": "gameround",
  "data": {
    "unique_id": "9cd823d3fe",
    "timestamp": "2024-12-12T12:17:53.988Z",
    "player_id": "StQ-1",
    "game_id": "GD8",
    "round_id": "f7ltidMBAwexDojlJBY",
    "amount": 0.5,
    "currency": "EUR",
    "is_win": false,
    "is_bonus": false
  }
}


Sending Events with Low Latency in Batches

To ensure timely processing, events should be sent with minimal delay. Unibo supports batching based on time and event count.
  • Time-based batching: collect events for up to 500 ms before sending a batch.
  • Event-count–based batching: collect up to 10,000 events per batch. If more than 10,000 events are collected within the 500 ms window, excess events should be sent in separate batches.
This approach minimizes latency while avoiding excessive request overhead.


Additional Considerations

If your infrastructure or casino operates in a different geographical region than Unibo’s primary instance (Ireland), a regional deployment can be configured to reduce latency. Please contact Unibo to discuss regional setup options.