Leaderboard rank changed

Body

application/json

The webhook event.

type

enum<string>

required

The webhook event type.

Available options:

leaderboard.rank_changed

user

User · object

required

The user whose rank changed.

Show child attributes

user.id

string

required

The ID of the user in your database. Must be a string.

Example:

"user-id"

user.email

string | null

required

The user's email address.

Example:

"[email protected]"

user.name

string | null

required

The name of the user.

Example:

"John Doe"

user.tz

string | null

required

The user's timezone.

Example:

"Europe/London"

user.deviceTokens

string[]

required

The user's device tokens.

The device token.

Example:

["token1", "token2"]

Whether the user is opted into receiving Trophy-powered emails.

Example:

true

user.attributes

object

required

User attributes as key-value pairs. Keys must match existing user attributes set up in the Trophy dashboard.

Show child attributes

user.attributes.{key}

string

Example:

{
  "department": "engineering",
  "role": "developer"
}

user.control

boolean

required

Whether the user is in the control group, meaning they do not receive emails or other communications from Trophy.

Example:

false

user.created

string<date-time>

required

The date and time the user was created, in ISO 8601 format.

Example:

"2021-01-01T00:00:00Z"

user.updated

string<date-time>

required

The date and time the user was last updated, in ISO 8601 format.

Example:

"2021-01-01T00:00:00Z"

leaderboard

WebhookUserLeaderboardResponse · object

required

The user's leaderboard data that changed. A user's data for a specific leaderboard including rank, value, and history. 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.rank

integer | null

required

The user's current rank in this leaderboard. Null if the user is not on the leaderboard.

Example:

2

leaderboard.value

integer | null

required

The user's current value in this leaderboard. Null if the user is not on the leaderboard.

Example:

4500

leaderboard.previousRank

integer | null

required

The user's rank before this event, or null if they were not on the leaderboard.

Example:

5

leaderboard.previousValue

integer | null

required

The user's value before this event, or null if they were not on the leaderboard.

Example:

1000

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

Leaderboard rank changed

Body

Response