WebGame Connect

Overview

Mini games are web pages loaded inside the mssgs client via an iframe/webview. The platform handles all session management, player tracking, and lifecycle — your game just needs to respond to webhooks and render a web UI.

How It Works

Game Registration

Each game is registered with the following fields:

Web URL

When a player joins a game session, the mssgs client loads your web_url with query parameters appended:

{web_url}?session={session_id}&game_user={game_user_id}

Webhooks

Your backend receives POST requests with a JSON body from the mssgs platform as players interact with the game session. These are fire-and-forget — failures do not affect the game session.

Webhook Headers

Webhook JSON Body

{
  "session": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "display_name": "CoolPlayer42",
  "game_user": "de875d3a",
  "game_guid": "f8a1b2c3-d4e5-6789-0abc-def123456789",
  "avatar_url": "https://example.com/avatar.png",
  "host": true,
  "callback_url": "https://mss.gs/api/v1/game-webhook/c9a1b2c3-d4e5-6789-0abc-def123456789"
}

Join Webhook

Called when a player joins the session. The host field is only present when the joining player is the one who created the session. Use this to identify the game host (e.g. for starting the game, managing settings).

The min_players and max_players fields are included in join webhooks.

Leave Webhook

Called when a player explicitly leaves the session. The host field is only present when the leaving player is the session host. You may want to handle host migration or end the game when the host leaves.

Callback URL

Every webhook includes a callback_url — a token-authenticated URL that lets you update the game channel metadata visible to all server members.

{
  "description": "Round 3 — Waiting for answers...",
  "thumbnail": "data:image/png;base64,iVBORw0KGgo..."
}

Both fields are optional. The payload merges into existing channel data, so you can update just the description or just the thumbnail.

Responses

Example

const thumbnailBase64 = 'data:image/png;base64,' + fs.readFileSync('thumbnail.png', 'base64');
await fetch(callbackUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    description: `Round ${round} of ${totalRounds} — ${currentQuestion}`,
    thumbnail: thumbnailBase64
  })
});

Security

Use game_user for Player Identity

The game_user ID is the only player identifier sent to the client-side game (via the web URL). It is:

• Unique per player per session
• An opaque 8-character string
• Not reused across sessions

Player display names are only sent to your backend via webhooks, never to the client-side game. This prevents players from spoofing identities and keeps personal information out of the browser.

Validate session and game_user on your Backend

Your game's web page will send session and game_user to your backend (e.g. via WebSocket or API calls). Always validate that:

1. The session is a known, active session (received via a join webhook)
2. The game_user was registered via a join webhook for that session
3. The game_user has not already left (received via a leave webhook)

Webhook Signature Verification

If webhook_secret is configured, every webhook includes an X-Mssgs-Signature header containing an HMAC-SHA256 signature of the request body.

The signature format is: sha256={hex_signature}

Verification steps

1. Read the raw request body (before parsing JSON)
2. Compute HMAC-SHA256 using your webhook_secret
3. Compare the result with the X-Mssgs-Signature header

const crypto = require('crypto');

function verifyWebhook(req, webhookSecret) {
  const signature = req.headers['x-mssgs-signature'];
  if (!signature) return false;

  const expectedSig = 'sha256=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(req.rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSig)
  );
}

import hmac
import hashlib

def verify_webhook(raw_body: bytes, signature: str, webhook_secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        webhook_secret.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Game Lifecycle

Architecture

Your backend maintains the game state. The mssgs platform only handles session lifecycle and player tracking — all game logic lives on your side.

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  mssgs Client   │     │  mssgs Gateway   │     │  Your Backend   │
│  (loads iframe) │     │  (orchestrator)  │     │  (game logic)   │
└────────┬────────┘     └────────┬─────────┘     └────────┬────────┘
         │                       │                         │
         │  Player joins session │                         │
         │──────────────────────>│                         │
         │                       │  POST webhook_join_url  │
         │                       │────────────────────────>│
         │                       │                         │ Store player
         │  Load web_url?session=&game_user=               │
         │<──────────────────────│                         │
         │                       │                         │
         │  Connect to your backend with session+game_user │
         │────────────────────────────────────────────────>│
         │                       │                         │ Validate
         │                       │                         │ game_user
         │  Game data (via your own WebSocket/API)         │
         │<────────────────────────────────────────────────│
         │                       │                         │

Best Practices