Top.gg Documentation

/

Webhooks

Webhook integration for receiving vote data


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. 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 2XX status response (like 200) in order to be considered successful. Unsuccessful webhooks are retried.

Official Top.gg libraries 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

FieldTypeDescription
botsnowflakeDiscord ID of the bot that received a vote.
usersnowflakeDiscord ID of the user who voted.
typestringThe type of the vote (should always be "upvote" except when using the test button it's "test").
isWeekendbooleanWhether the weekend multiplier is in effect, meaning users votes count as two.
query?stringQuery string params found on the /bot/:ID/vote page. Example: ?a=1&b=2.

Server Webhooks

FieldTypeDescription
guildsnowflakeDiscord ID of the guild that received a vote.
usersnowflakeDiscord ID of the user who voted.
typestringThe type of the vote (should always be "upvote" except when using the test button it's "test").
query?stringQuery 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.

You are currently viewing v0.
Edit on GitHub