Webhook Event Reference for Top.gg

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.

Field	Type	Description
`type`	string	Always `"vote.create"`
`data.id`	string	Top.gg vote ID (snowflake)
`data.weight`	number	Vote weight (`1` normally, `2` during weekend multiplier)
`data.created_at`	string	ISO 8601 timestamp when the vote was cast
`data.expires_at`	string	ISO 8601 timestamp when the user can vote again
`data.project.id`	string	Top.gg project ID
`data.project.type`	string	Project type (`"bot"` or `"server"`)
`data.project.platform`	string	Platform (always `"discord"`)
`data.project.platform_id`	string	Discord client ID of the bot or guild ID of the server
`data.query`	object	Parsed query parameters appended to the `/:id/vote` page URL. For example, `/:id/vote?key1=value&key2=value2` sends the parsed query arguments in `data.query`.
`data.user.id`	string	Top.gg user ID of the voter
`data.user.platform_id`	string	Discord user ID of the voter
`data.user.name`	string	Discord username of the voter
`data.user.avatar_url`	string	Avatar 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"
    },
    "query": {
      "key1": "value",
      "key2": "value2"
    },
    "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.

Field	Type	Description
`type`	string	Always `"webhook.test"`
`data.project.id`	string	Top.gg project ID
`data.project.type`	string	Project type (`"bot"` or `"server"`)
`data.project.platform`	string	Platform (always `"discord"`)
`data.project.platform_id`	string	Discord client ID or guild ID
`data.user.id`	string	Top.gg user ID of the tester
`data.user.platform_id`	string	Discord user ID of the tester
`data.user.name`	string	Discord username of the tester
`data.user.avatar_url`	string	Avatar 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.

Bot webhook

Field	Type	Description
`bot`	string	Discord ID of the bot that was voted for
`user`	string	Discord ID of the user who voted
`type`	string	`"upvote"` for real votes, `"test"` when triggered from the dashboard
`isWeekend`	boolean	`true` when the weekend multiplier is active (votes count as 2)
`query`	string (optional)	Query string parameters appended to the `/bot/:id/vote` page URL

{
  "bot": "803190510032756736",
  "user": "160105994217586689",
  "type": "upvote",
  "isWeekend": false,
  "query": ""
}

Get Started

Webhooks

Libraries

Resources

Webhook Event Reference for Top.gg

`vote.create`

`webhook.test`

Legacy v0 webhook events

​vote.create

​webhook.test

​Legacy v0 webhook events

`vote.create`

`webhook.test`

Legacy v0 webhook events