Scoring

Each challenge uses either decay or dynamic scoring. Decay is the default and gives every solver the same number of points. Dynamic scoring accepts a different score for each team from an external service.

You set the scoring kind from the admin challenge editor under /admin/challs or directly through the admin challenge update API. The platform refuses to switch a challenge’s scoring kind while solves exist. Wipe the solves first, or pick the kind when you create the challenge.

Challenge types

Decay

The default. Every solver receives the same point value, and that value decreases as more teams solve the challenge. The math is controlled by the global scoring provider, which sees the challenge’s points.min and points.max along with the current solve count.

1
{
2
  "points": { "min": 100, "max": 500 },
3
  "scoring": { "kind": "decay" }
4
}

Editing points.min or points.max on a decay challenge immediately re-prices every existing solver. Switching the scoring algorithm globally also re-prices every decay challenge on the next worker tick.

Some scoring providers compare a challenge against maxSolves, the highest solve count among decay challenges. Dynamic challenges are excluded from that calculation, since their scores come from an external source.

Dynamic

The points for a dynamic challenge come from an external scoring source that publishes per-team values over time. Every team can have a different score on the same challenge, and the scores can move up or down as the source publishes updates. Dynamic scoring works well for king-of-the-hill, attack-defense, and other scoring systems that run outside rCTF.

1
{
2
  "scoring": {
3
    "kind": "dynamic",
4
    "source": {
5
      "transport": "webhook",
6
      "secret": "<shared-secret>"
7
    }
8
  }
9
}

Dynamic scoring guide

Dynamic challenges talk to rCTF through a webhook. Your scoring backend POSTs the current per-team scores whenever they change.

Team identifiers

Every entry in the score list references an rCTF team ID, the same UUID that appears on the /users/:id page. The dynamic backend needs to know each team’s ID somehow. A few patterns tend to work.

• Have admins paste each team’s rCTF ID into the dynamic service’s onboarding flow.
• Wire a “Sign in with rCTF” button on the dynamic service through External apps and read the team ID from GET /api/v1/users/me once the user lands back authorized. This is usually the lowest-friction option when teams self-onboard.

Scores for unknown team IDs are silently ignored. Keep a record of the IDs you send if you need to confirm that every team was updated.

Request body

The webhook uses this JSON body:

1
{
2
  "scores": [
3
    { "userId": "11111111-2222-3333-4444-555555555555", "points": 1280 },
4
    { "userId": "66666666-7777-8888-9999-000000000000", "points": 940 }
5
  ]
6
}

Each entry replaces that team’s current score for the challenge. Teams omitted from the payload keep their existing score.

Webhook

Send a POST /api/v2/challs/:id/scores request whenever a team’s score changes. rCTF saves the new values, records the change for the historical graph, and tells the leaderboard worker to recalculate the standings.

Endpoint

1
POST /api/v2/challs/<challenge-id>/scores HTTP/1.1
2
Host: ctf.example.com
3
Content-Type: application/json
4
X-RCTF-Timestamp: <unix-milliseconds>
5
X-RCTF-Signature: sha256=<hex>
6

7
{"scores":[{"userId":"…","points":1280}]}

The route is public and authenticates requests with the HMAC signature, timestamp, and replay check. The shared secret protects the scoreboard and should be handled like a password.

Responses

Reference publisher

import { createHmac } from 'node:crypto'

const RCTF_BASE_URL = 'https://ctf.example.com'
const CHALLENGE_ID = 'koth-pwn-2026'
const SECRET = process.env.RCTF_DYNAMIC_SECRET!

type ScoreEntry = { userId: string; points: number }

export async function publishScores(scores: ScoreEntry[]) {
  const body = JSON.stringify({ scores })
  const timestamp = Date.now().toString()
  const signature =
    'sha256=' +
    createHmac('sha256', SECRET).update(`${timestamp}.${CHALLENGE_ID}.${body}`).digest('hex')

  const res = await fetch(`${RCTF_BASE_URL}/api/v2/challs/${CHALLENGE_ID}/scores`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-rctf-timestamp': timestamp,
      'x-rctf-signature': signature,
    },
    body,
  })

  if (!res.ok) {
    throw new Error(`rCTF rejected scores: ${res.status} ${await res.text()}`)
  }
  return (await res.json()) as {
    data: { inserted: number; updated: number; deleted: number }
  }
}

How scores reach the leaderboard

rCTF stores each team’s current points in solves.points and records every change in score_events. Each history entry includes the point difference and its source (flag, decay-recompute, feed, ban, delete, or algo-change).

• The leaderboard worker sums each team’s solves.points to produce ranks. Decay recomputes are debounced through Redis pub/sub so a burst of solves only re-prices the challenge once.
• The leaderboard graph replays score_events chronologically so historical points reflect what the team had at that point in time, not what they have now.
• Banning a team records the removal of its solve points, while unbanning records their return. Both actions recalculate affected decay challenges.
• Deleting a solve records the corresponding point removal.

You don’t need to interact with score_events directly. It’s an internal audit log, and its fields are documented above to help explain discrepancies between the /scores page and the /scores/:id graph.