Tournament Webhooks

Overview

Tournament webhooks deliver real-time notifications for tournament lifecycle events. All tournament webhooks follow the verification process described in Webhook Setup.

Prerequisites

• Webhook endpoint configured per Webhook Setup

• Subscribed to relevant tournament event types

• Signature verification implemented

Event Types

Event	Trigger
TournamentCreated	New tournament created
TournamentEdited	Tournament details modified via API
TournamentUserJoined	User joins tournament
TournamentCanceled	Tournament canceled
TournamentCompleted	Tournament completed with results

Common Payload Structure

All tournament webhook events share a base structure:

{
  "event": "TournamentCreated",
  "tenantId": "YOUR_TENANT_ID",
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Weekend Golf Tournament",
    "description": "Monthly championship event",
    "type": "CASH_FIXED",
    "status": "OPEN",
    "buyInAmount": 20,
    "maxParticipants": 100,
    "minPayoutAmount": 500,
    "fee": 10,
    "scoringType": "LOWEST_SCORE",
    "gameId": "golf-masters-2025",
    "locationId": "location-uuid",
    "startsAt": "2025-06-15T10:00:00Z",
    "expiresAt": "2025-06-15T18:00:00Z",
    "paymentStructure": [
      { "position": 1, "value": 500 },
      { "position": 2, "value": 300 },
      { "position": 3, "value": 200 }
    ],
    "users": [
      {
        "userId": "user-uuid",
        "score": 72,
        "rank": 1,
        "canSubmitNewScore": true,
        "reward": null
      }
    ],
    "metadataString": "{\"customField\":\"value\"}"
  }
}

Base Fields

• event (string) - Event type identifier

• tenantId (string) - Your tenant identifier

• matchup (object) - Tournament data (matches GET tournament API response)

Matchup Object

The matchup object structure matches the response from the Get Tournament endpoint and includes:

• id - Tournament UUID

• title - Tournament name

• type - CASH_FIXED or CASH_PERCENTAGE

• status - Current tournament status

• buyInAmount - Entry fee

• maxParticipants - Maximum participants

• scoringType - HIGHEST_SCORE or LOWEST_SCORE

• paymentStructure - Prize distribution

• users - Array of participants with scores and rankings

• And all other tournament properties

Event Details

TournamentCreated

Triggered when a new tournament is created.

Payload:

{
  "event": "TournamentCreated",
  "tenantId": "YOUR_TENANT_ID",
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Weekend Golf Tournament",
    "status": "OPEN",
    "buyInAmount": 20,
    "users": [],
    ...
  }
}

Use Cases:

• Notify users of new tournament availability

• Publish tournament to external platforms

• Initialize tournament tracking systems

• Send promotional notifications

TournamentEdited

Triggered when tournament properties are modified via API.

Payload:

{
  "event": "TournamentEdited",
  "tenantId": "YOUR_TENANT_ID",
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Updated Tournament Name",
    ...
  }
}

Use Cases:

• Notify participants of tournament changes

• Update external listings

• Log audit trail of modifications

• Trigger re-validation logic

Notes:

• Payload contains updated tournament state

• Compare with previous state to determine what changed

• Not all field changes may trigger this event

TournamentUserJoined

Triggered when a user joins the tournament.

Payload:

{
  "event": "TournamentUserJoined",
  "tenantId": "YOUR_TENANT_ID",
  "newUserId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "users": [
      {
        "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "score": null,
        "rank": null,
        "canSubmitNewScore": true
      },
      ...
    ],
    ...
  }
}

Additional Fields:

• newUserId (string) - UUID of the user who joined

Use Cases:

• Notify other participants of new competitor

• Update participant count displays

• Trigger welcome messages

• Update tournament capacity tracking

Notes:

• Full user details available in matchup.users array

• newUserId provides quick access to joining user

TournamentCanceled

Triggered when a tournament is canceled.

Payload:

{
  "event": "TournamentCanceled",
  "tenantId": "YOUR_TENANT_ID",
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "CANCELED",
    "users": [...],
    ...
  }
}

Use Cases:

• Process refunds for participants

• Send cancellation notifications

• Remove from active tournament listings

• Log cancellation reasons

Notes:

• Entry fees automatically refunded to participants

• Tournament removed from active queries

• Check metadataString for cancellation reason if provided

TournamentCompleted

Triggered when tournament is finalized with results.

Payload:

{
  "event": "TournamentCompleted",
  "tenantId": "YOUR_TENANT_ID",
  "mode": "auto",
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "CLOSED",
    "users": [
      {
        "userId": "winner-uuid",
        "score": 68,
        "rank": 1,
        "reward": {
          "type": "CASH",
          "value": "500.00"
        }
      },
      {
        "userId": "second-uuid",
        "score": 72,
        "rank": 2,
        "reward": {
          "type": "CASH",
          "value": "300.00"
        }
      }
    ],
    ...
  }
}

Additional Fields:

• mode (string) - Reward resolution method:

  • "auto" - Rewards calculated by Lucra scoring logic

  • "manual" - Rewards assigned via API completion request

Use Cases:

• Distribute winnings

• Update player statistics and leaderboards

• Send completion notifications with results

• Archive tournament data

• Trigger achievement/badge systems

Notes:

• matchup.users includes final scores, rankings, and rewards

• Rewards already distributed by platform

• Check mode to understand how winners were determined

Webhook Handling Best Practices

Idempotency

Tournament webhooks may be redelivered. Implement idempotent handling:

interface WebhookLog {
  matchupId: string;
  eventType: string;
  processedAt: Date;
}

async function handleTournamentWebhook(payload: TournamentWebhook) {
  const { event, matchup } = payload;

  // Check if already processed
  const existing = await db.webhookLogs.findOne({
    matchupId: matchup.id,
    eventType: event,
  });

  if (existing) {
    console.log(`Duplicate webhook: ${event} for ${matchup.id}`);
    return; // Already processed
  }

  // Process webhook
  await processTournamentEvent(payload);

  // Log processing
  await db.webhookLogs.create({
    matchupId: matchup.id,
    eventType: event,
    processedAt: new Date(),
  });
}

User Joined Event Optimization

When handling TournamentUserJoined, use newUserId to avoid scanning the full users array:

async function handleUserJoined(payload: TournamentUserJoinedWebhook) {
  const { newUserId, matchup } = payload;

  // Quick access to new user
  const newUser = matchup.users.find((u) => u.userId === newUserId);

  // Send welcome notification
  await sendNotification(newUserId, {
    type: 'tournament_joined',
    tournamentId: matchup.id,
    tournamentTitle: matchup.title,
  });

  // Update capacity tracking
  await updateTournamentCapacity(matchup.id, matchup.users.length);
}

Completion Mode Handling

Handle different completion modes appropriately:

async function handleTournamentCompleted(payload: TournamentCompletedWebhook) {
  const { mode, matchup } = payload;

  if (mode === 'auto') {
    // Lucra determined winners automatically
    await logAutoCompletion(matchup);
  } else if (mode === 'manual') {
    // Winners assigned via API
    await logManualCompletion(matchup);
  }

  // Process rewards regardless of mode
  for (const user of matchup.users) {
    if (user.reward) {
      await recordReward(user.userId, user.reward);
    }
  }
}

Error Handling

Return appropriate HTTP status codes to control webhook redelivery:

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

    const payload = req.body;

    // Handle webhook
    await handleTournamentWebhook(payload);

    res.status(200).send('OK');
  } catch (error) {
    if (error.isRetriable) {
      // Return 5xx to trigger retry
      res.status(500).send('Temporary error');
    } else {
      // Return 2xx to prevent retry on permanent errors
      console.error('Permanent error:', error);
      res.status(200).send('OK');
    }
  }
});

TypeScript Types

interface TournamentWebhookBase {
  event: string;
  tenantId: string;
  matchup: TournamentMatchup;
}

interface TournamentCreatedWebhook extends TournamentWebhookBase {
  event: 'TournamentCreated';
}

interface TournamentEditedWebhook extends TournamentWebhookBase {
  event: 'TournamentEdited';
}

interface TournamentUserJoinedWebhook extends TournamentWebhookBase {
  event: 'TournamentUserJoined';
  newUserId: string;
}

interface TournamentCanceledWebhook extends TournamentWebhookBase {
  event: 'TournamentCanceled';
}

interface TournamentCompletedWebhook extends TournamentWebhookBase {
  event: 'TournamentCompleted';
  mode: 'auto' | 'manual';
}

type TournamentWebhook =
  | TournamentCreatedWebhook
  | TournamentEditedWebhook
  | TournamentUserJoinedWebhook
  | TournamentCanceledWebhook
  | TournamentCompletedWebhook;

Related Documentation

• Tournaments REST API - Tournament management endpoints

• Webhook Setup - Webhook subscription and verification

• Games You Play Webhooks - GYP game webhooks