Docs/Relay Stats & Leaderboards
Features

Relay Stats & Leaderboards

Easily connect the results of your Relay matches to Leaderboards or webhooks. This lets you update global rankings automatically or notify your backend, Discord server, or any other service when a match ends.

Quick Overview

Track Match Data

Track custom stats such as score, kills, match time, status, or any other structured result you want to keep.

Send To Leaderboards

Route per-player or match-level stats into Leaderboards automatically when the Relay match finishes.

Post To Webhooks

Send the full match result payload to your own backend, analytics pipeline, or Discord bot for post-match workflows.

Use this together with the Unity Client API stat helpers and the Leaderboards docs if you want both in-match stat tracking and automatic post-match score submission.

Setting Up Tracked Stats

  1. In Unity, go to the top menu: Assets > TurnKit > Config. Open the Relay configuration you want to edit.
  2. Scroll to the Tracked Stats section and click Add.
  3. Fill in the fields for each stat.

Name

A friendly stat name such as Score, Kills, or TimeSurvived.

Data Type

Choose double, string, or list of strings depending on what you want to store.

Scope

Use PER_PLAYER for separate values per player or MATCH for a single shared match value.

Initial Value

The starting value for the stat. Numeric stats usually begin at 0.

Destination

Choose LEADERBOARD to update a board automatically or WEBHOOK to include the stat in the webhook result payload.

ID

Select the target leaderboard or webhook from the generated dropdown. If a new option is missing, regenerate enums on the config screen.

// Per-player leaderboard stat
Relay.Stat(ExampleConfig.Stats.Score)
    .ForPlayer(Relay.MySlot)
    .Add(125);

// Match-level webhook stat
Relay.Stat(ExampleConfig.Stats.MatchWinner).Set("player1");

// String-list webhook stat
Relay.Stat(ExampleConfig.Stats.Tags).Add("ranked", "daily_challenge");

Adding Webhooks

  1. In the same Relay Config, go to the Webhooks section.
  2. Click Add.
  3. Fill in the webhook details below.

ID

A unique identifier that later appears in the tracked stat destination dropdown.

URL

The endpoint that will receive match data, such as your backend or a Discord webhook bridge.

Headers

Optional custom headers such as Authorization if your endpoint requires them. We recommend adding an X-TurnKit-Secret header to your config and verifying it on your server to ensure incoming match data is authentic.

Webhooks are useful when you want authoritative match results outside TurnKit. Common patterns include notifying a Discord bot, writing analytics events, granting backend rewards, or forwarding verified outcomes into your own systems after the match ends.

Example Webhook Payload

When a match ends, TurnKit sends a JSON payload containing the terminal reason, session identifiers, tracked stats, and player information.

{
  "endReason": "END_GAME",
  "gameKeyId": "18ecd7ed-3a3d-463a-aafc-9ccf0e380b8f",
  "matchDurationSeconds": 5,
  "matchEndedAt": "2026-04-14T14:06:38.427308800Z",
  "matchStats": { ... },
  "playerStats": { ... },
  "players": [
    {
      "playerId": "player1",
      "slot": 1
    },
    {
      "playerId": "player2",
      "slot": 2
    }
  ],
  "relayConfigSlug": "example",
  "sessionId": "7725aa8c-fc30-49e2-97e7-607e16c25195"
}

If you need the match transport details behind these events, continue to the WebSocket Protocol docs. If you want the destination to be a ranking system, use this page alongside the Leaderboards guide.

Relay Stats & Leaderboards - TurnKit Docs