Leaderboard finished

Events fire between 13:00-13:59 UTC the day following the end of a leaderboard run. This is because each leaderboard run is relative to each user’s time zone, and users in the most delayed time zones must be given the chance to finish.

Events only include the top 10 user rankings. To fetch more, use the single leaderboard API.

Body

application/json

The webhook event.

type

enum<string>

required

The webhook event type.

Available options:

leaderboard.finished

leaderboard

LeaderboardResponseWithRankings · object

required

The leaderboard run that finished and its final rankings. A leaderboard with its configuration details.

Show child attributes

leaderboard.id

string

required

The unique ID of the leaderboard.

Example:

"5100fe51-6bce-6j44-b0hs-bddc4e123682"

leaderboard.name

string

required

The user-facing name of the leaderboard.

Example:

"Weekly Word Count Challenge"

leaderboard.key

string

required

The unique key used to reference the leaderboard in APIs.

Example:

"weekly-words"

leaderboard.rankBy

enum<string>

required

What the leaderboard ranks by.

Available options:

points,

streak,

metric

Example:

"metric"

leaderboard.breakdownAttribute

string | null

required

The key of the attribute to break down this leaderboard by.

Example:

"country"

leaderboard.description

string | null

required

The user-facing description of the leaderboard.

Example:

"Compete weekly to see who writes the most words"

leaderboard.start

string<date>

required

The start date of the leaderboard in YYYY-MM-DD format.

Example:

"2025-01-01"

leaderboard.end

string<date> | null

required

The end date of the leaderboard in YYYY-MM-DD format, or null if it runs forever.

Example:

"2025-12-31"

leaderboard.maxParticipants

integer

required

The maximum number of participants in the leaderboard.

Example:

100

leaderboard.runUnit

enum<string> | null

required

The repetition type for recurring leaderboards, or null for one-time leaderboards.

Available options:

day,

month,

year,

Example:

"day"

leaderboard.runInterval

integer | null

required

The interval between repetitions, relative to the start date and repetition type. Null for one-time leaderboards.

Example:

7

leaderboard.status

enum<string>

required

The status of the leaderboard.

Available options:

active,

scheduled,

finished

Example:

"active"

leaderboard.rankings

LeaderboardRanking · object[]

required

Array of user rankings for the leaderboard.

Show child attributes

leaderboard.rankings.userId

string

required

The ID of the user.

Example:

"user-123"

leaderboard.rankings.userName

string | null

required

The name of the user. May be null if no name is set.

Example:

"Alice Johnson"

leaderboard.rankings.rank

integer

required

The user's rank in the leaderboard.

Example:

1

leaderboard.rankings.value

integer

required

The user's value for this leaderboard (points, metric value, etc.).

Example:

5000

leaderboard.metricKey

string

The key of the metric to rank by, if rankBy is 'metric'.

Example:

"words-written"

leaderboard.metricName

string

The name of the metric to rank by, if rankBy is 'metric'.

Example:

"Words Written"

leaderboard.pointsSystemKey

string

The key of the points system to rank by, if rankBy is 'points'.

Example:

"xp-system"

leaderboard.pointsSystemName

string

The name of the points system to rank by, if rankBy is 'points'.

Example:

"Experience Points"

Response

200

Return a 200 status to indicate the webhook was received and processed.

Overview

Achievements

Streaks

Points

Leaderboards

Body

Response