Event Stream

Introduction

The Event Stream enables your provider 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 provider 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

In addition, Unibo may receive updates related to players and games through the Event 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

Providers 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 providers 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,
  }
}

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.

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.

Campaign Lifecycle Webhooks

To help providers optimize event delivery and reduce traffic, Unibo supports campaign lifecycle webhooks. These webhook notifications allow providers to send game round and transaction events only when they are relevant to active campaigns and the associated player and game selections.

The following campaign lifecycle events are available:

• CAMPAIGN_GOING_LIVE_SOON – indicates that a campaign matching specific game and player selection criteria will become active shortly. Providers can use this notification to prepare event streaming for the affected audience and games.

• CAMPAIGN_HAS_BEEN_FINISHED – indicates that a campaign has ended and event delivery is no longer required for the associated game and player selections.

• CAMPAIGN_SELECTION_CHANGED – indicates that the player and/or game selection criteria for an active campaign have been updated. Providers should adjust their event delivery logic accordingly.

By leveraging these webhooks, providers can dynamically control which events are sent to Unibo, ensuring that only data required for active campaign processing is transmitted.

Detailed information about webhook configuration, payload structures, security, delivery guarantees, and implementation examples can be found in the Webhook Integration Guide section.

If additional webhook events, payload fields, or integration capabilities are required to meet specific client requirements, Unibo can work with providers to implement suitable extensions as part of the integration process.

Additional Considerations

If your infrastructure or provider 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.