Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.top.gg/llms.txt

Use this file to discover all available pages before exploring further.

Top.gg webhooks deliver two event types on the v1 system: vote.create, fired when a user votes for your project, and webhook.test, sent when you trigger a test from the dashboard. The legacy v0 system uses different schemas for bots and servers, described at the bottom of this page.

​
vote.create

Top.gg fires this event each time a user upvotes your project. Use it to reward voters, update leaderboards, or log activity.
The weight field indicates how many votes this event counts as. During weekend double-vote periods, weight is 2.
FieldTypeDescription
typestringAlways "vote.create"
data.idstringTop.gg vote ID (snowflake)
data.weightnumberVote weight (1 normally, 2 during weekend multiplier)
data.created_atstringISO 8601 timestamp when the vote was cast
data.expires_atstringISO 8601 timestamp when the user can vote again
data.project.idstringTop.gg project ID
data.project.typestringProject type ("bot" or "server")
data.project.platformstringPlatform (always "discord")
data.project.platform_idstringDiscord client ID of the bot or guild ID of the server
data.user.idstringTop.gg user ID of the voter
data.user.platform_idstringDiscord user ID of the voter
data.user.namestringDiscord username of the voter
data.user.avatar_urlstringAvatar URL of the voter
{
  "type": "vote.create",
  "data": {
    "id": "808499215864008704",
    "weight": 1,
    "created_at": "2026-02-09T00:47:14.2510149+00:00",
    "expires_at": "2026-02-09T12:47:14.2510149+00:00",
    "project": {
      "id": "803190510032756736",
      "type": "bot",
      "platform": "discord",
      "platform_id": "160105994217586689"
    },
    "user": {
      "id": "top.gg id",
      "platform_id": "discord id",
      "name": "username",
      "avatar_url": "<avatar url>"
    }
  }
}

​
webhook.test

This event is always available and lets you verify your endpoint is reachable before real votes arrive. Send a test from your project’s Webhooks page in the dashboard.
FieldTypeDescription
typestringAlways "webhook.test"
data.project.idstringTop.gg project ID
data.project.typestringProject type ("bot" or "server")
data.project.platformstringPlatform (always "discord")
data.project.platform_idstringDiscord client ID or guild ID
data.user.idstringTop.gg user ID of the tester
data.user.platform_idstringDiscord user ID of the tester
data.user.namestringDiscord username of the tester
data.user.avatar_urlstringAvatar URL of the tester
{
  "type": "webhook.test",
  "data": {
    "user": {
      "id": "top.gg id",
      "platform_id": "discord id",
      "name": "username",
      "avatar_url": "<avatar url>"
    },
    "project": {
      "id": "803190510032756736",
      "type": "bot",
      "platform": "discord",
      "platform_id": "160105994217586689"
    }
  }
}

​
Legacy v0 webhook events

The v0 webhook system uses simpler, flat payload schemas. Bot and server webhooks have different shapes.
FieldTypeDescription
botstringDiscord ID of the bot that was voted for
userstringDiscord ID of the user who voted
typestring"upvote" for real votes, "test" when triggered from the dashboard
isWeekendbooleantrue when the weekend multiplier is active (votes count as 2)
querystring (optional)Query string parameters appended to the /bot/:id/vote page URL
{
  "bot": "803190510032756736",
  "user": "160105994217586689",
  "type": "upvote",
  "isWeekend": false,
  "query": ""
}