Games You Play Webhooks

Overview

Games You Play (GYP) webhooks deliver real-time notifications for recreational game events. All GYP webhooks follow the verification process described in Webhook Setup.

Prerequisites

• Webhook endpoint configured per Webhook Setup

• Subscribed to relevant GYP event types

• Signature verification implemented

Event Types

Event	Trigger
RecreationalGameCreated	New recreational game created
RecreationalGameJoined	User joins a game
RecreationalGameCanceled	Game canceled
RecreationalGameCompleted	Game completed with outcome
RecreationalGameStarted	Game started by owner

Payload Structure

All GYP webhook events share a common payload structure:

{
  "event": "RecreationalGameCreated",
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "createdByUserId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "gameId": "nfl-game-12345",
    "winnerGroupId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "status": "OPEN",
    "type": "RECREATIONAL_GAME",
    "subtype": "GROUP_VS_GROUP",
    "buyInAmount": 7,
    "isPublic": true,
    "groups": [
      {
        "groupId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "Team Alpha",
        "users": [
          {
            "userId": "user-uuid-1",
            "reward": {
              "type": "CASH",
              "value": "14.00",
              "metadata": {}
            }
          }
        ]
      }
    ]
  }
}

Payload Fields

Root Level

• event (string) - Event type identifier

• matchup (object) - Game details

Matchup Object

• id (string) - UUID of the matchup

• createdByUserId (string) - UUID of user who created the game

• gameId (string) - External game identifier

• winnerGroupId (string|null) - UUID of winning group (null until completed)

• status (string) - Current game status (see statuses below)

• type (string) - Always RECREATIONAL_GAME for GYP

• subtype (string) - Game format: GROUP_VS_GROUP or FREE_FOR_ALL

• buyInAmount (number) - Entry cost per player

• isPublic (boolean) - Whether game is publicly joinable

• groups (array) - Participating groups/teams

Group Object

• groupId (string) - UUID of the group

• name (string) - Group/team name

• users (array) - Players in this group

User Object

• userId (string) - UUID of the user

• userMetadata (string) - Custom user metadata

• reward (object|null) - Reward information (populated on completion)

Reward Object

• type (string) - Reward type: CASH or TENANT_REWARD

• value (string) - Reward amount or value

• metadata (object) - Additional reward information

Game Statuses

• OPEN - Game created, accepting players

• CONFIRMED - Minimum players joined

• LOCKED - No more players can join

• PENDING_OUTCOMES - Awaiting results

• CLOSED - Completed with winner

• CLOSED_TIE - Completed in tie

• CANCELED_BY_OWNER - Canceled by creator

• CANCELED_NOT_ACCEPTED - Canceled due to insufficient players

• CANCELED_THROUGH_API - Canceled via API

• CANCELED_TIMEOUT - Canceled due to timeout

Event Details

RecreationalGameCreated

Triggered when a new recreational game is created.

Typical Status: OPEN

Use Cases:

• Notify players of new game availability

• Track game creation metrics

• Update external systems

Example:

{
  "event": "RecreationalGameCreated",
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "OPEN",
    "buyInAmount": 10,
    ...
  }
}

RecreationalGameJoined

Triggered when a user joins an existing game.

Typical Status: OPEN or CONFIRMED

Use Cases:

• Notify other players of new participant

• Update participant counts

• Trigger game confirmation logic

RecreationalGameStarted

Triggered when the game owner starts the game.

Typical Status: LOCKED or PENDING_OUTCOMES

Use Cases:

• Lock game roster

• Begin tracking game progress

• Notify participants game has begun

RecreationalGameCompleted

Triggered when game outcome is determined.

Typical Status: CLOSED or CLOSED_TIE

Use Cases:

• Distribute winnings

• Update player statistics

• Trigger reward fulfillment

Example:

{
  "event": "RecreationalGameCompleted",
  "matchup": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "CLOSED",
    "winnerGroupId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
    "groups": [
      {
        "groupId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "users": [
          {
            "userId": "user-uuid",
            "reward": {
              "type": "CASH",
              "value": "14.00"
            }
          }
        ]
      }
    ]
  }
}

RecreationalGameCanceled

Triggered when a game is canceled.

Typical Status: CANCELED_* (various cancellation reasons)

Use Cases:

• Process refunds

• Notify participants

• Update game listings

Webhook Handling Best Practices

Idempotency

Webhooks may be delivered multiple times. Implement idempotent handling using the matchup id:

async function handleGYPWebhook(payload: GYPWebhookPayload) {
  const { event, matchup } = payload;

  // Check if already processed
  const processed = await isWebhookProcessed(matchup.id, event);
  if (processed) {
    return; // Already handled
  }

  // Process webhook
  await processWebhook(payload);

  // Mark as processed
  await markWebhookProcessed(matchup.id, event);
}

Status Transitions

Track expected status transitions to detect anomalies:

const VALID_TRANSITIONS = {
  OPEN: ['CONFIRMED', 'CANCELED_*'],
  CONFIRMED: ['LOCKED', 'CANCELED_*'],
  LOCKED: ['PENDING_OUTCOMES', 'CANCELED_*'],
  PENDING_OUTCOMES: ['CLOSED', 'CLOSED_TIE', 'DISPUTE'],
};

Error Handling

Return 2xx status codes for successful processing. Lucra will retry failed webhook deliveries:

app.post('/webhooks/gyp', async (req, res) => {
  try {
    await handleGYPWebhook(req.body);
    res.status(200).send('OK');
  } catch (error) {
    // Log error but return 200 if webhook is valid but processing failed
    if (error.retriable) {
      res.status(500).send('Retry');
    } else {
      res.status(200).send('OK'); // Don't retry unrecoverable errors
    }
  }
});

Related Documentation

• Games You Play REST API - REST endpoints for game management

• Webhook Setup - Webhook subscription and verification

• Free-to-Play Webhooks - Free-to-play game webhooks