Setting up Webhooks for Vote Events
Learn how to receive real-time notifications when users vote for your bot or server. Implement reward systems, analytics tracking, and user engagement features with webhooks.
Setup Overview
Get webhooks working in 4 simple steps
Set Webhook URL
Configure endpoint
Add Authorization
Secure with auth token
Handle Requests
Process vote events
Test & Deploy
Verify webhook works
Prerequisites
Standard Webhooks
- A publicly accessible web server (HTTP or HTTPS)
- SSL certificate recommended for security
- Custom code to handle webhook data
Discord Webhooks (Easy Setup)
- No server setup required
- Discord channel with webhook URL
- Automatic vote announcements
Security Recommendation
While HTTP endpoints are supported for development and testing, we strongly recommend using HTTPS in production to protect your webhook data and authorization tokens from interception.
Need a server?
Consider using services like Railway, Heroku, DigitalOcean, or AWS to host your webhook endpoint. Many offer free tiers perfect for webhook handling and provide automatic HTTPS.Or use Discord webhooks for a simpler no-server solution!
Discord Webhook Setup (Simple Option)
No Server Required!
If you don't want to set up a web server, you can use Discord webhooks instead! Rank.top will automatically detect Discord webhook URLs and send formatted messages directly to your Discord channel when users vote.
What you get:
- Automatic vote announcements in your Discord channel
- User mentions and vote counts
- Rank.top branding and logo
- No coding or server management required
Example message:

@username has cast the 1,234th vote for @YourBot! 🎉
How to set up a Discord webhook:
- 1
Go to your Discord server
Navigate to the channel where you want vote announcements
- 2
Open channel settings
Right-click the channel → Edit Channel → Integrations → Webhooks
- 3
Create a new webhook
Click "New Webhook" and give it a name (e.g., "Vote Notifications")
- 4
Copy the webhook URL
It will look like:
https://discord.com/api/webhooks/...
- 5
Paste in Rank.top settings
Go to your bot/server edit page → Webhooks tab → paste the Discord webhook URL
- 6
Test it!
Use the test button to see a vote announcement in your Discord channel
That's it!
No authorization token needed for Discord webhooks. Rank.top automatically detects Discord webhook URLs and sends appropriately formatted messages.
Standard Webhook Data Format
This section applies to standard webhooks only
Discord webhooks are handled automatically by Rank.top. If you're using a Discord webhook URL, you can skip this section - no coding required!
Request Structure
When a user votes, Rank.top sends a POST request to your webhook URL with this structure:
Headers
Example JSON Body
Field Descriptions
Authorization
headerYour webhook authentication token (sent in request headers)
type
stringAlways "vote" for vote events
target_type
stringAlways "bot" for bot webhooks, "server" for server webhooks
target_id
stringThe ID of the bot or server that was voted for
is_test
booleanTrue for test webhooks, false for real votes
user_id
stringDiscord ID of the user who voted
timestamp
numberUnix timestamp when the vote occurred (in seconds)
guild_id
string?Discord guild ID where bot was voted from (requires search param ?guildId=guildId in the URL)
Implementation Examples
Node.js (Express)
Python (Flask)
Discord.js Bot Integration
Configuration Steps
Setting up in Rank.top
- 1
Navigate to your bot/server settings
Go to your dashboard and click "Edit" on your listing
- 2
Go to the Webhooks tab
Find the webhook configuration section in the sidebar
- 3
Enter your webhook URL
Choose one of these options:
Standard webhooks:
https://yourserver.com/webhook/vote
http://your-ip-address:port/webhook/vote
Discord webhooks:
https://discord.com/api/webhooks/1234567890/abc...
- 4
Set an authorization token (optional)
For standard webhooks: Use a secure random string and store it in your environment variables.
For Discord webhooks: Leave this blank - not needed! - 5
Test your webhook
Use the built-in test button to verify everything works
Security Best Practices
Always verify authorization headers
Check the Authorization header against your stored token to prevent unauthorized requests.
HTTPS is strongly recommended
While HTTP endpoints are supported, HTTPS ensures secure data transmission and protects against eavesdropping.
Implement timeout handling
Respond within 10 seconds to avoid webhook retries and potential duplicates.
Handle retry logic gracefully
Failed webhooks are retried up to 6 times with increasing intervals.
Troubleshooting
Webhook not receiving requests
- Verify your webhook URL is publicly accessible
- Check that your server is running and listening on the correct port
- Ensure your firewall allows incoming connections
- Test with the built-in webhook tester in your bot settings
Getting 401 Unauthorized errors
- Verify the authorization token matches exactly
- Check for extra whitespace or special characters in your token
- Ensure you're reading the Authorization header (not the request body)
- Make sure your environment variables are loaded correctly
Receiving duplicate vote events
- Implement idempotency using the timestamp field
- Respond with 200 status code quickly to prevent retries
- Check your server logs for timeout issues