Loyalty System Integration Full Closed Beta

The loyalty system integration enables two-way data sync between your backend systems and FanFest's loyalty engine. When users earn points through shows, contests, referrals, or any channel action, your systems can receive that data in real time or query it on demand.

Closed Beta

This integration tier is in Closed Beta and available to select partners. The API specification described here is subject to change. Contact us for access.

How It Works

FanFest's loyalty engine tracks every user action — quiz answers, poll votes, referrals, check-ins, and more. Each action generates points based on your channel's leaderboard configuration. The egress system makes this data available to your backend through two delivery mechanisms:

Push (Webhooks) — FanFest sends an HTTP POST to your endpoint every time a loyalty action occurs. Your system receives data in real time without polling.

Pull (REST API) — Your system queries FanFest's REST endpoints on demand to fetch loyalty actions, point totals, or configuration status.

Both mechanisms deliver data in the same format, determined by your channel's resolution mode.

Resolution Modes

Every channel's egress configuration specifies a resolution mode that controls the granularity of loyalty data:

Mode	Description	Best For
Aggregated	All-time totals per user, per action	Displaying point balances, simple dashboards
Day Aggregated	Daily bucketed totals per user, per action	Reconciliation, daily reporting
High Fidelity	Individual action records with full detail	Audit trails, real-time analytics

All three modes use a discriminated union on the resolution field, so your code can branch on the payload type. See Resolution Modes for payload schemas and examples.

Recommendation

Start with Aggregated mode. It is the simplest to consume and sufficient for most display and sync use cases. You can upgrade to a higher-fidelity mode later without changing your webhook endpoint.

Architecture Overview

When a user performs a loyalty action:

1. FanFest's loyalty engine emits a UserActionCreated event to EventBridge
2. The event is routed to an SQS queue for reliable, ordered processing
3. A Lambda function resolves the payload using your channel's resolution mode
4. The payload is delivered via HMAC-signed POST to each of your registered webhook endpoints

For pull access, your backend authenticates with an API key and queries the REST endpoints directly.

Prerequisites

Before setting up the loyalty integration, you need:

1. A working SSO integration — Tier 3 builds on Tier 2 (SSO). Users must be identified across platforms for loyalty data to be meaningful.

2. An API key with loyalty:read permission — Generated in the API Keys section of your channel admin panel. The key must include the loyalty:read permission scope.

3. An HTTPS webhook endpoint (for push integration) — Your endpoint must be publicly reachable over HTTPS. HTTP endpoints are rejected for security. The endpoint should respond with a 2xx status code within 10 seconds.

Next Steps

• Webhooks — Register endpoints, verify HMAC signatures, handle retries
• REST API — Query actions and points on demand with API key auth
• Resolution Modes — Understand the three data granularity options
• Egress Endpoints Reference — Full REST endpoint specification
• Webhook Payloads Reference — Complete payload schemas with TypeScript interfaces