WebGame Connect

Overzicht

Mini games zijn webpagina's die binnen de mssgs client worden geladen via een iframe/webview. Het platform verzorgt al het sessiebeheer, speler tracking en lifecycle — jouw game hoeft alleen te reageren op webhooks en een web UI te renderen.

Hoe het werkt

Game Registratie

Elke game wordt geregistreerd met de volgende velden:

Web URL

Wanneer een speler een game sessie joint, laadt de mssgs client jouw web_url met query parameters:

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

Webhooks

Jouw backend ontvangt POST requests met een JSON body van het mssgs platform wanneer spelers interacteren met de game sessie. Deze zijn fire-and-forget — mislukkingen hebben geen invloed op de game sessie.

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

Wordt aangeroepen wanneer een speler de sessie joint. Het host veld is alleen aanwezig wanneer de joinende speler degene is die de sessie heeft aangemaakt. Gebruik dit om de game host te identificeren (bijv. voor het starten van de game, beheren van instellingen).

De min_players en max_players velden zijn opgenomen in join webhooks.

Leave Webhook

Wordt aangeroepen wanneer een speler de sessie expliciet verlaat. Het host veld is alleen aanwezig wanneer de vertrekkende speler de sessie host is. Je wilt mogelijk host migratie afhandelen of de game beëindigen wanneer de host vertrekt.

Callback URL

Elke webhook bevat een callback_url — een token-geauthenticeerde URL waarmee je de game kanaal metadata kunt bijwerken die zichtbaar is voor alle serverleden.

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

Beide velden zijn optioneel. De payload wordt samengevoegd met bestaande kanaaldata, zodat je alleen de beschrijving of alleen de thumbnail kunt bijwerken.

Responses

Voorbeeld

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
  })
});

Beveiliging

Gebruik game_user voor Speler Identiteit

De game_user ID is de enige speler identifier die naar de client-side game wordt gestuurd (via de web URL). Het is:

• Uniek per speler per sessie
• Een opaque 8-karakter string
• Wordt niet hergebruikt tussen sessies

Weergavenamen van spelers worden alleen naar jouw backend gestuurd via webhooks, nooit naar de client-side game. Dit voorkomt dat spelers identiteiten kunnen vervalsen en houdt persoonlijke informatie uit de browser.

Valideer session en game_user op je Backend

De webpagina van jouw game stuurt session en game_user naar jouw backend (bijv. via WebSocket of API calls). Valideer altijd dat:

1. De session een bekende, actieve sessie is (ontvangen via een join webhook)
2. De game_user geregistreerd is via een join webhook voor die sessie
3. De game_user niet al vertrokken is (ontvangen via een leave webhook)

Webhook Signature Verificatie

Als webhook_secret is geconfigureerd, bevat elke webhook een X-Mssgs-Signature header met een HMAC-SHA256 signature van de request body.

Het signature formaat is: sha256={hex_signature}

Verificatiestappen

1. Lees de ruwe request body (voordat JSON wordt geparsed)
2. Bereken HMAC-SHA256 met jouw webhook_secret
3. Vergelijk het resultaat met de 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

Architectuur

Jouw backend beheert de game state. Het mssgs platform verzorgt alleen de sessie lifecycle en speler tracking — alle game logica draait aan jouw kant.

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  mssgs Client   │     │  mssgs Gateway   │     │  Jouw Backend   │
│ (laadt iframe)  │     │  (orchestrator)  │     │  (game logica)  │
└────────┬────────┘     └────────┬─────────┘     └────────┬────────┘
         │                       │                         │
         │  Speler joint sessie  │                         │
         │──────────────────────>│                         │
         │                       │  POST webhook_join_url  │
         │                       │────────────────────────>│
         │                       │                         │ Speler opslaan
         │  Laad web_url?session=&game_user=               │
         │<──────────────────────│                         │
         │                       │                         │
         │  Verbind met je backend met session+game_user   │
         │────────────────────────────────────────────────>│
         │                       │                         │ Valideer
         │                       │                         │ game_user
         │  Game data (via je eigen WebSocket/API)         │
         │<────────────────────────────────────────────────│
         │                       │                         │

Best Practices