Webhooks
Instead of requesting our API to see the users who have voted for your bot, you can now use webhooks! Webhooks will send a POST request to a URL of your choice when your bot has been voted for.
Getting Started
Start by setting up your webhook URL in the edit form of your bot on this site, it can be found at https://top.gg/bot/:your-bot-id/webhooks (Replace :your-bot-id with your bot's ID!). Once you've entered the URL you want the webhook to be sent to, you're all set! If you need help setting up webhooks inside of your bot don't be afraid to ask in our discord server in the #topgg-api channel.
Security
On the edit page you can see another input for Authorization. Here you can provide a shared secret that you can check for on the server side.
To verify requests are coming from us, look for the value in the Authorization header and make sure it is the same as the value you provided in the form.
If you're running a firewall, you can whitelist the following IPs, which will be used to deliver webhooks for the foreseeable future.
| IP |
|---|
159.203.105.187 |
Acknowledgement
Webhooks sent by top.gg must be acknowledged with a 200 response in order to be considered successful. Unsuccessful webhooks are retried.
Top.gg libraries that handle webhooks acknowledge webhooks automatically.
Timeouts
Responses to webhooks must be returned within 5 seconds, otherwise they are considered a timeout and will be queued for a retry (if available).
Retrial
Webhook requests that time out or return a 5XX status response (like 500) will be retried up to 10 times. The retry delay is increased exponentially per retry by 2^N seconds, from a minimum delay of 1 second for the first retry up to 17 minutes for the tenth.
Errors resulting with status 4XX (like 404) will not be retried as these are considered user errors.
Data Format
The format of the data your webhook URL will receive in a POST request.
Schema
Bot Webhooks
| Field | Type | Description |
|---|---|---|
| bot | snowflake | Discord ID of the bot that received a vote. |
| user | snowflake | Discord ID of the user who voted. |
| type | string | The type of the vote (should always be "upvote" except when using the test button it's "test"). |
| isWeekend | boolean | Whether the weekend multiplier is in effect, meaning users votes count as two. |
| query? | string | Query string params found on the /bot/:ID/vote page. Example: ?a=1&b=2. |
Server Webhooks
| Field | Type | Description |
|---|---|---|
| guild | snowflake | Discord ID of the guild that received a vote. |
| user | snowflake | Discord ID of the user who voted. |
| type | string | The type of the vote (should always be "upvote" except when using the test button it's "test"). |
| query? | string | Query string params found on the /servers/:ID/vote page. Example: ?a=1&b=2. |
More Events
Looking for webhooks events other than votes? They are only available starting from v1 of the API.