External Events — Technical Overview

ResultFly ingests external events from customer systems so campaigns can react to the same signals that drive CRM, POS, or loyalty decisions. This document captures the behavioral contract: it intentionally avoids schema details, storage internals, and advanced replay/streaming capabilities.

Terminology

• External Event — an incoming fact or signal from an external system that ResultFly uses to adjust campaigns.
• Source — the system that emits the event (CRM, POS, loyalty backend, custom service, etc.).
• External Event ID — the stable identifier the source assigns to each event.
• User Identity — the external identifier that links the event to a ResultFly user (see Identity & Authentication — Technical Overview).
• User State — the collection of values ResultFly stores for a user (balances, variables, eligibility).

External Events are not outbound notifications, UI interactions, or analytics events. They only flow from brand systems into ResultFly; the platform never emits them toward end users.

1. External Events Overview

ResultFly accepts external events because brands already capture the key milestones of their customer journeys inside CRM, POS, and loyalty stacks. Feeding those milestones into ResultFly lets campaigns award points, unlock content, or trigger automations without duplicating logic inside the platform. Events describe what happened; ResultFly decides how to react. This approach differs from direct state updates: instead of telling the platform “set balance = 150,” the brand sends the underlying fact (“purchase completed”), and ResultFly applies the configured rules.

2. External Event Model (High-Level)

External Events follow a flexible logical model:

• A reference to the user via one or more identities.
• The source that emitted the event, so ResultFly can apply trust and deduplication policies per system.
• An external event ID that stays stable for that fact.
• An event type, fully defined by the client (for example purchase_recorded, loyalty_tier_upgraded).
• Optional attributes that give context (amount, store code, promo tag, etc.).

ResultFly does not enforce a rigid transaction schema. Brands can send whatever attributes make sense for their campaigns as long as the identity and external event ID remain consistent.

3. Event Processing Flow

1. The source system sends an external event over the authenticated server-to-server channel.
2. ResultFly resolves the user via Identity rules; unknown identities can follow the pre-provisioning path described below.
3. The platform checks whether the combination of source and external event ID already exists.
4. If the event is new, the campaign or server-side logic evaluates the type and attributes.
5. Any resulting changes apply to User State (balances, attempts, eligibility) and are persisted.
6. ResultFly records the processing outcome alongside the event metadata for auditability.

4. Deduplication & Idempotency Guarantees

ResultFly guarantees that each (source, external_event_id) pair mutates User State at most once. When the same event arrives again—whether due to retries, batch replays, or manual resubmission—the platform acknowledges receipt but skips the effect. This protects users from double rewards and shields integrations from strict delivery requirements. Brands can rely on “exactly once per source and external event ID” while still using simple retry mechanisms on their side.

5. Pre-Provisioned Users

External Events do not require the user to exist beforehand. If the identity cannot be resolved, ResultFly can create a new user record, bind the provided identity, and immediately apply the event. This means loyalty accruals, bonuses, or access flags can be prepared long before the person visits the campaign interface. When that participant eventually authenticates (or even if they never do), the pre-loaded User State is already present.

6. Relationship to User State

External Events are the canonical drivers of User State. They may increase balances, adjust attempts, flip eligibility flags, or update custom variables that steer flows. Exactly how those effects map to campaign mechanics is defined by campaign configuration and will be detailed in the forthcoming User State — Technical Overview. The key principle is that ResultFly responds to events instead of arbitrary state mutations.

7. Error Semantics (High-Level)

• 401 Unauthorized — authentication failed (invalid service credentials). Non-retriable until credentials are refreshed.
• 403 Forbidden — credentials lack scope for the target campaign or integration. Non-retriable until access is granted.
• 404 Not Found — the referenced identity is unknown and auto-creation is disabled, or the target campaign/operation does not exist. Retriable only after correcting identity or configuration.
• 409 Conflict — the incoming event conflicts with already processed data (duplicate (source, external_event_id) or incompatible state). Retriable only if the source assigns a new identifier intentionally; otherwise treat as a hard stop.

8. Out-of-Scope

The current version does not include:

• Event replay or reprocessing features.
• Automatic merging of events or user records.
• Ordering guarantees across different sources or channels.
• Outbound webhooks or mirrored notifications.
• Streaming or real-time subscription feeds.

9. Security & Trust Model

External Events are accepted exclusively over authenticated server-to-server channels. ResultFly trusts that the source emits accurate facts and enforces access control per integration, but the source remains responsible for data quality, business validation, and compliance with privacy policies.