Free-to-Play Webhooks

Overview

Free-to-Play (FTP) webhooks deliver real-time notifications for game lifecycle events, focusing on matchup creation, acceptance, and outcome distribution. All FTP webhooks follow the verification process described in Webhook Setup.

Prerequisites

• Webhook endpoint configured per Webhook Setup

• Subscribed to FTP event types

• Signature verification implemented

• Reward fulfillment system integrated

Event Types

Event	Trigger	Frequency
FtpMatchupCreated	New FTP matchup created	Once per matchup
FtpMatchupAccepted	User accepts matchup	Once per acceptance (not for creator)
ContestUserOutcome	Matchup completes	Once per participant

Matchup Types

Free-to-Play games support three matchup types:

Type	Description
PROFESSIONAL_SPORTS_TEAM_STAT	Prediction based on team statistics
PROFESSIONAL_SPORTS_PLAYER_STAT	Prediction based on player statistics
RECREATIONAL_GAME	Custom recreational game predictions

Event Details

FtpMatchupCreated

Triggered when a new Free-to-Play matchup is created.

Payload:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "FtpMatchupCreated",
  "createdByUserId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "PROFESSIONAL_SPORTS_PLAYER_STAT",
  "isPublic": true,
  "groups": [
    {
      "groupId": "group-uuid-1",
      "users": [
        {
          "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "tenantReward": {
            "id": "reward-uuid",
            "intentId": "promo-2025-q2",
            "metadata": "{\"type\":\"discount\",\"value\":\"15\"}"
          }
        }
      ],
      "professionalPlayerDetails": {
        "player": "LeBron James",
        "schedule": "Lakers vs Warriors - 2025-06-15",
        "metric": "Points Over 25.5"
      }
    },
    {
      "groupId": "group-uuid-2",
      "users": [],
      "professionalPlayerDetails": {
        "player": "LeBron James",
        "schedule": "Lakers vs Warriors - 2025-06-15",
        "metric": "Points Under 25.5"
      }
    }
  ]
}

Field Descriptions:

Field	Type	Description
id	string	UUID of the matchup
event	string	Always "FtpMatchupCreated"
createdByUserId	string	UUID of creating user
type	string	Matchup type (see types above)
isPublic	boolean	Whether matchup is publicly joinable
groups	array	Competing groups/sides

Group Object:

Field	Type	Description
groupId	string	UUID of the group
users	array	Users in this group
professionalTeamDetails	object	Team details (if type is PROFESSIONAL_SPORTS_TEAM_STAT)
professionalPlayerDetails	object	Player details (if type is PROFESSIONAL_SPORTS_PLAYER_STAT)

User Object:

Field	Type	Description
userId	string	UUID of the user
tenantReward	object	Reward configuration for this user

Tenant Reward Object:

Field	Type	Description
id	string	Lucra's tenant reward identifier
intentId	string	Your custom identifier (passed via SDK)
metadata	string	JSON string with custom reward data (passed via SDK)

Professional Player Details:

Field	Type	Description
player	string	Player name
schedule	string	Game schedule information
metric	string	Statistical prediction metric

Professional Team Details:

Field	Type	Description
team	string	Team name
schedule	string	Game schedule information
metric	string	Statistical prediction metric

Use Cases:

• Log new matchup creation

• Track matchup types and popularity

• Monitor reward configuration

• Initialize matchup tracking in your system

FtpMatchupAccepted

Triggered when a user accepts an existing FTP matchup.

Notes:

• Fires once per acceptance

• Does NOT fire for the initial creator

• In 1v1 scenarios, fires once when opponent accepts

Payload:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "FtpMatchupAccepted",
  "createdByUserId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "acceptedByUserId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "type": "PROFESSIONAL_SPORTS_PLAYER_STAT",
  "isPublic": false,
  "groups": [
    {
      "groupId": "group-uuid-1",
      "users": [
        {
          "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "tenantReward": {
            "id": "reward-uuid-1",
            "intentId": "promo-2025-q2",
            "metadata": "{\"type\":\"discount\",\"value\":\"15\"}"
          }
        }
      ],
      "professionalPlayerDetails": {
        "player": "LeBron James",
        "schedule": "Lakers vs Warriors - 2025-06-15",
        "metric": "Points Over 25.5"
      }
    },
    {
      "groupId": "group-uuid-2",
      "users": [
        {
          "userId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
          "tenantReward": {
            "id": "reward-uuid-2",
            "intentId": "promo-2025-q2",
            "metadata": "{\"type\":\"discount\",\"value\":\"15\"}"
          }
        }
      ],
      "professionalPlayerDetails": {
        "player": "LeBron James",
        "schedule": "Lakers vs Warriors - 2025-06-15",
        "metric": "Points Under 25.5"
      }
    }
  ]
}

Additional Fields:

• acceptedByUserId (string) - UUID of the user who accepted the matchup

Use Cases:

• Notify creator of matchup acceptance

• Lock matchup roster

• Send confirmation messages

• Track matchup fill rates

Differences from FtpMatchupCreated:

• Includes acceptedByUserId field

• Both groups now populated with users

• Indicates matchup is ready to start

ContestUserOutcome

Triggered when a Free-to-Play matchup completes, sent once per participant.

Important: Each participant receives their own webhook notification.

Payload:

{
  "event": "ContestUserOutcome",
  "matchupId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "usersOutcomes": [
    {
      "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "outcome": "WIN",
      "reward": {
        "intentId": "promo-2025-q2",
        "metadata": "{\"type\":\"discount\",\"value\":\"15\",\"expiresAt\":\"2025-08-31T23:59:59Z\"}"
      }
    },
    {
      "userId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "outcome": "LOSS",
      "reward": null
    }
  ]
}

Field Descriptions:

Field	Type	Description
event	string	Always "ContestUserOutcome"
matchupId	string	UUID of the completed matchup
userId	string	UUID of user receiving this notification
usersOutcomes	array	Outcomes for all participants

User Outcome Object:

Field	Type	Description
userId	string	UUID of the participant
outcome	string	Result: WIN, LOSS, or TIE
reward	object|null	Reward details (only for winners/ties)

Reward Object:

Field	Type	Description
intentId	string	Your custom identifier from SDK
metadata	string	JSON string with reward details from SDK

Use Cases:

• Distribute rewards to winners

• Send outcome notifications

• Update user statistics

• Track game completion metrics

Processing Pattern:

async function handleContestUserOutcome(webhook: ContestUserOutcomeWebhook) {
  const { matchupId, userId, usersOutcomes } = webhook;

  // Find outcome for the user receiving this webhook
  const userOutcome = usersOutcomes.find((o) => o.userId === userId);

  if (!userOutcome) {
    throw new Error(`Outcome not found for user ${userId}`);
  }

  if (userOutcome.outcome === 'WIN' && userOutcome.reward) {
    // Grant reward
    const rewardMetadata = JSON.parse(userOutcome.reward.metadata);
    await grantReward(userId, rewardMetadata);

    // Notify Lucra of redemption
    await markRewardRedeemed(matchupId, userId);

    // Send winner notification
    await sendNotification(userId, {
      type: 'ftp_win',
      matchupId,
      reward: rewardMetadata,
    });
  } else if (userOutcome.outcome === 'LOSS') {
    // Send consolation message
    await sendNotification(userId, {
      type: 'ftp_loss',
      matchupId,
    });
  } else if (userOutcome.outcome === 'TIE' && userOutcome.reward) {
    // Handle tie with reward
    const rewardMetadata = JSON.parse(userOutcome.reward.metadata);
    await grantReward(userId, rewardMetadata);
    await markRewardRedeemed(matchupId, userId);
  }
}

Webhook Handling Best Practices

Idempotency for ContestUserOutcome

Since each user receives their own webhook, implement user-specific idempotency:

interface OutcomeProcessingRecord {
  matchupId: string;
  userId: string;
  outcome: string;
  processedAt: Date;
}

async function handleContestUserOutcomeIdempotent(webhook: ContestUserOutcomeWebhook) {
  const { matchupId, userId } = webhook;

  // Check if already processed for this user
  const existing = await db.outcomeRecords.findOne({
    matchupId,
    userId,
  });

  if (existing) {
    console.log(`Outcome already processed for user ${userId} in ${matchupId}`);
    return;
  }

  // Process outcome
  await processOutcome(webhook);

  // Record processing
  await db.outcomeRecords.create({
    matchupId,
    userId,
    outcome: webhook.usersOutcomes.find((o) => o.userId === userId)?.outcome,
    processedAt: new Date(),
  });
}

Reward Metadata Parsing

Safely parse and validate reward metadata:

interface RewardMetadata {
  type: string;
  value: string;
  expiresAt?: string;
  conditions?: any;
}

function parseRewardMetadata(metadataString: string): RewardMetadata {
  try {
    const parsed = JSON.parse(metadataString);

    // Validate required fields
    if (!parsed.type || !parsed.value) {
      throw new Error('Missing required reward fields');
    }

    return parsed as RewardMetadata;
  } catch (error) {
    console.error('Failed to parse reward metadata:', metadataString);
    throw new Error('Invalid reward metadata format');
  }
}

// Usage
const outcome = usersOutcomes.find((o) => o.userId === userId);
if (outcome?.reward) {
  const rewardDetails = parseRewardMetadata(outcome.reward.metadata);
  await grantReward(userId, rewardDetails);
}

Matchup State Tracking

Track matchup progression through webhook events:

enum FtpMatchupState {
  CREATED = 'CREATED',
  ACCEPTED = 'ACCEPTED',
  COMPLETED = 'COMPLETED',
}

interface FtpMatchupRecord {
  matchupId: string;
  state: FtpMatchupState;
  createdByUserId: string;
  acceptedByUserId?: string;
  type: string;
  createdAt: Date;
  acceptedAt?: Date;
  completedAt?: Date;
}

async function updateMatchupState(event: string, matchupId: string, data: any) {
  switch (event) {
    case 'FtpMatchupCreated':
      await db.ftpMatchups.create({
        matchupId,
        state: FtpMatchupState.CREATED,
        createdByUserId: data.createdByUserId,
        type: data.type,
        createdAt: new Date(),
      });
      break;

    case 'FtpMatchupAccepted':
      await db.ftpMatchups.update(
        { matchupId },
        {
          state: FtpMatchupState.ACCEPTED,
          acceptedByUserId: data.acceptedByUserId,
          acceptedAt: new Date(),
        }
      );
      break;

    case 'ContestUserOutcome':
      await db.ftpMatchups.update(
        { matchupId },
        {
          state: FtpMatchupState.COMPLETED,
          completedAt: new Date(),
        }
      );
      break;
  }
}

Reward Fulfillment Pipeline

Implement a robust reward fulfillment pipeline:

async function fulfillRewardPipeline(
  userId: string,
  matchupId: string,
  reward: { intentId: string; metadata: string }
) {
  try {
    // 1. Parse reward details
    const rewardDetails = parseRewardMetadata(reward.metadata);

    // 2. Validate reward is still valid
    if (rewardDetails.expiresAt && new Date(rewardDetails.expiresAt) < new Date()) {
      throw new Error('Reward has expired');
    }

    // 3. Grant reward in your system
    const grantResult = await grantReward(userId, rewardDetails);

    // 4. Notify Lucra of successful redemption
    await markRewardRedeemed(matchupId, userId);

    // 5. Send user notification
    await sendNotification(userId, {
      type: 'reward_granted',
      reward: rewardDetails,
      grantId: grantResult.id,
    });

    // 6. Log successful fulfillment
    await logRewardFulfillment({
      matchupId,
      userId,
      intentId: reward.intentId,
      status: 'success',
      grantedAt: new Date(),
    });
  } catch (error) {
    // Log failure for manual review
    await logRewardFulfillment({
      matchupId,
      userId,
      intentId: reward.intentId,
      status: 'failed',
      error: error.message,
      failedAt: new Date(),
    });

    // Queue for retry
    await queueRewardRetry(matchupId, userId, reward);

    throw error;
  }
}

Error Handling

Return appropriate status codes to control webhook redelivery:

app.post('/webhooks/ftp', async (req, res) => {
  try {
    // Verify signature
    if (!verifySignature(req)) {
      return res.status(401).send('Invalid signature');
    }

    const { event } = req.body;

    switch (event) {
      case 'FtpMatchupCreated':
        await handleFtpMatchupCreated(req.body);
        break;
      case 'FtpMatchupAccepted':
        await handleFtpMatchupAccepted(req.body);
        break;
      case 'ContestUserOutcome':
        await handleContestUserOutcome(req.body);
        break;
      default:
        console.warn(`Unknown FTP event: ${event}`);
    }

    res.status(200).send('OK');
  } catch (error) {
    console.error('FTP webhook error:', error);

    if (error.retriable) {
      // Return 5xx to trigger Lucra retry
      res.status(500).send('Temporary error');
    } else {
      // Return 2xx to prevent retry on permanent errors
      res.status(200).send('OK');
    }
  }
});

TypeScript Types

interface FtpMatchupCreatedWebhook {
  id: string;
  event: 'FtpMatchupCreated';
  createdByUserId: string;
  type: 'PROFESSIONAL_SPORTS_TEAM_STAT' | 'PROFESSIONAL_SPORTS_PLAYER_STAT' | 'RECREATIONAL_GAME';
  isPublic: boolean;
  groups: FtpGroup[];
}

interface FtpMatchupAcceptedWebhook extends FtpMatchupCreatedWebhook {
  event: 'FtpMatchupAccepted';
  acceptedByUserId: string;
}

interface ContestUserOutcomeWebhook {
  event: 'ContestUserOutcome';
  matchupId: string;
  userId: string;
  usersOutcomes: UserOutcome[];
}

interface UserOutcome {
  userId: string;
  outcome: 'WIN' | 'LOSS' | 'TIE';
  reward: {
    intentId: string;
    metadata: string;
  } | null;
}

interface FtpGroup {
  groupId: string;
  users: FtpUser[];
  professionalTeamDetails?: {
    team: string;
    schedule: string;
    metric: string;
  };
  professionalPlayerDetails?: {
    player: string;
    schedule: string;
    metric: string;
  };
}

interface FtpUser {
  userId: string;
  tenantReward: {
    id: string;
    intentId: string;
    metadata: string;
  };
}

Related Documentation

• Free-to-Play REST API - Reward redemption endpoint

• Webhook Setup - Webhook subscription and verification

• Games You Play Webhooks - Standard GYP webhooks