Event-based Integration (EBI)
This page outlines the requirements, assumptions, and supported behaviors for implementing an Events-based Integration (EBI) with Optimove. Use it to scope an integration, confirm what the batch pipeline supports, and avoid common setup issues.
The EBI is an onboarding path for clients who Stream event-based data rather than maintaining batch exports. Optimove ingests out-of-the-box (OOTB) events, maps and processes them through the batch flow, and configures the instance based on the incoming events — no additional batch infrastructure required.
How the Integration Works
Data is available from go-live. Historical data can be loaded separately (see Historical Data).
- Send events according to Optimove's OOTB event definitions. This lets Optimove automatically ingest and process event-based data and configure the instance from incoming events.
- OOTB events drive automatic mapping and processing in the batch flow to support Optimove's OOTB solution.
- Extend beyond OOTB using self-serve tools — Real-Time Attributes, API Attributes, and others.
For the full event schemas and mandatory properties, see Optimove's OOTB Events for Data Integration and the Mandatory Properties for Standard Events reference.
Assumptions & Constraints
Review these constraints carefully — they define the boundaries of what the integration supports and how edge cases are handled.
Historical Data
EBI instances no longer have to start empty. In addition to the real-time events you send from go-live, Optimove can load historical data into your instance, so that customer profiles, attributes, and reporting reflect past activity from day one.
Historical data is loaded as a separate, one-time process. It is not sent through your real-time event stream, which prevents historical events from triggering real-time campaigns.
Note: Historical loads are scoped with Optimove before any data is sent. To start the process, contact:
- During onboarding: your Optimove Project Manager and your Data Solutions Engineer.
- After go-live: your Customer Success Manager (CSM) and your Data Solutions Engineer.
How It Works
- Scope the load with Optimove. Agree on the following before sending anything:
- How far back the data goes.
- Which events to include. These are the same events required for your vertical (see OOTB Events per Vertical).
- The expected data volume.
- Receive your SFTP folder. Optimove provides a dedicated folder on the SFTP environment for your region (US or EU). Each tenant has its own folder, and data is never shared across tenants. Your Data Solutions Engineer grants you access to the folder.
- Upload your historical files. Upload them to the
inbound/folder inside your tenant's directory. - Optimove loads and validates. Optimove processes the files, loads them into your instance, and reviews the results with you before sign-off.
A historical load can run during onboarding, before go-live, or later, once your instance is already live.
Historical data must end at your go-live date. Activity from go-live onward is covered by your real-time events.
Folder Structure
<tenant_name>/
inbound/ <- upload historical files hereFile Format
Historical data is sent as CSV files containing OOTB events. Each event must follow the OOTB event structure and include the mandatory parameters for that event (see Mandatory Properties for Standard Events).
The exact file format is agreed during scoping. Contact your Data Solutions Engineer for the format specification before you prepare your files.
Working with a Partner
If your data is delivered through an integration partner, the partner uploads historical files directly to your tenant's inbound/ folder, not to a shared partner folder. Optimove converts the partner's data into OOTB events as part of the load. The file format is agreed during onboarding.
Bespoke Attributes (Self-Serve Model)
The batch pipeline supports standardized OOTB attributes only. Any bespoke (custom) attributes must be created outside the integration process using self-serve tools:
- Real-Time Attributes derived from event parameters
- Data Studio (CSV-based ingestion)
- Optimove APIs for direct attribute updates
This keeps delivery fast and reduces dependency on batch releases. For any use case that falls outside these guidelines, use Real-Time Attributes, Data Studio, or Optimove APIs rather than the batch pipeline.
Event Log Capacity
Event volume sent to Optimove must comply with agreed capacity limits:
ootb_registrationandootb_user_details_updatehave a rate limit of 50 requests per 10 seconds.- The server-side rate limit is up to 10,000 requests per second, with each request containing a maximum of 10 events.
Events are ingested based on event timestamps, not processing time. See Optimove's OOTB Events for Data Integration for full details.
Event Timestamp & UTC Alignment
Event timestamps may experience minor misalignments due to:
- Data processing delays
- Time zone normalization (UTC)
All event timestamps are processed and stored in UTC+0.
Monetary Amounts & Currency
- All monetary values must be sent in the Optimove site's configured currency.
- Currency conversion is not handled as part of the EBI.
Mandatory Parameters for OOTB Events
All mandatory and enrichment parameters defined for Optimove's OOTB events must be provided. Missing required parameters may result in:
- Event rejection
- Incomplete batch records
- Attribute calculation issues
Parameters sent asnullvalues will be reflected in the customer profile per instance. See the OOTB Events per Vertical table below for the full list of mandatory and enrichment parameters per vertical.
OOTB Events per Vertical
The following table lists the required OOTB events for each supported vertical. A ✓ indicates the event is required for that vertical; – indicates it is not applicable. Primary keys (PKs) identify unique event records.
| OOTB Event | Primary Keys (PKs) | Multi-Sport & Casino | Sport | Casino | Sweepstakes | Ecom |
|---|---|---|---|---|---|---|
ootb_registration | customer | ✓ | ✓ | ✓ | ✓ | ✓ |
ootb_user_details_update | customer | ✓ | ✓ | ✓ | ✓ | ✓ |
ootb_deposit | customer, ootb_transaction_id, timestamp | ✓ | ✓ | ✓ | ✓ | – |
ootb_withdrawal | customer, ootb_transaction_id, timestamp | ✓ | ✓ | ✓ | ✓ | – |
ootb_game_session | customer, timestamp, ootb_game_code | ✓ | – | ✓ | – | – |
ootb_sports_bet_placed | customer, timestamp, ootb_betslip_key, ootb_bet_key | ✓ | ✓ | – | – | – |
ootb_sports_bet_settled | customer, timestamp, ootb_betslip_key, ootb_bet_key | ✓ | ✓ | – | – | – |
ootb_sweepstakes_game_session | customer, timestamp, ootb_game_code | – | – | – | ✓ | – |
ootb_product_order_completed | customer, timestamp, ootb_order_id, ootb_item_order_id, ootb_product_id | – | – | – | – | ✓ |
ootb_product_refund | customer, timestamp, ootb_order_id, ootb_item_order_id, ootb_product_id, ootb_refund_id | – | – | – | – | ✓ |
For per-event parameter definitions, see the relevant event pages under Optimove's OOTB Events for Data Integration.
Updated 1 day ago
