Guide to Top.gg Webhooks: Features and Best Practices
Top.gg is a directory where people find and vote for Discord bots and servers. Its webhooks tell you the moment someone votes for your project, so your bot can hand out rewards, update a leaderboard or thank the voter without polling the API.
Top.gg has two webhook systems:
- v1 ; signed with
x-topgg-signature; the secret (whs_...) is generated when you save the URL. Events arevote.createandwebhook.test. - v0 (legacy) ; not signed. A shared secret you enter in the bot edit form is sent verbatim in the
Authorizationheader. Flat bodies withtypevaluesupvoteandtest.
Only v1 webhooks, whose secret starts with whs_, are supported. Legacy v0 webhooks aren't signed and fail verification.
This guide covers both systems, the vote.create payload, verifying the v1 signature, and a retry window that lasts only a few seconds.
What are Top.gg webhooks?
You set a webhook URL on your project's dashboard under Webhooks. For v1, saving the URL makes Top.gg generate a secret starting whs_. From then on, each vote produces a signed POST with a JSON body, and you can send a webhook.test from the same page to check your endpoint.
The older v0 system is still documented. It sends flat bodies, has separate shapes for bots and servers, and authenticates with a secret you choose, sent as-is in Authorization.
Top.gg webhook features
| Feature | Details |
|---|---|
| Signature | hex HMAC-SHA256 |
| Signature header | x-topgg-signature |
| Body | JSON |
| Event routing | Body field type |
From Top.gg's webhooks overview:
- Respond with a
2xxwithin 5 seconds. - Each request has an
x-topgg-traceheader with a trace ID to quote to Top.gg support. - Delivery limits differ by version:
| v1 | v0 (legacy) | |
|---|---|---|
| Timeout | 5 seconds | 5 seconds |
| Max retries | 3 | 10 |
| Retry delay | Exponential backoff, 2^N seconds (about 1s, 2s, 4s) | Exponential backoff, 2^N seconds (1s up to about 17 min) |
| Retry triggers | Timeout or 5xx | Timeout or 5xx (4xx are not retried) |
Events and payloads
Route on the top-level type.
| Event routing | Body field type |
vote.create
| Field | Type | Description |
|---|---|---|
data.id | string | Top.gg vote ID (snowflake); use it to deduplicate |
data.weight | number | 1 normally, 2 during weekend double-vote periods |
data.created_at / data.expires_at | string | ISO 8601 times: when the vote was cast and when the user can vote again |
data.project.id / .type / .platform / .platform_id | string | Top.gg project ID, "bot" or "server", always "discord", and the Discord client ID or guild ID |
data.query | object | Parsed query parameters from the /:id/vote page URL (/:id/vote?key1=value sends { "key1": "value" }) |
data.user.id / .platform_id / .name / .avatar_url | string | Top.gg user ID, Discord user ID, username and avatar URL of the voter |
The vote.create example from Top.gg's events page:
{
"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 has the same project and user objects, but no vote id, weight or times.
Legacy v0 (not supported by verification)
Bot bodies are flat: { "bot": "<discord id>", "user": "<discord id>", "type": "upvote" | "test", "isWeekend": false, "query": "" }.
Setting up Top.gg webhooks
- Open your project's dashboard on Top.gg and go to Webhooks.
- Paste your endpoint URL, for example
https://example.com/webhooks/top-gg, and save. - Copy the generated secret, prefix included, and store it as
TOPGG_WEBHOOK_SECRET. - Send a test from the Webhooks page and check that a
webhook.testarrives.
Don't confuse this with the v0 setup, where you type your own secret into the bot edit form. That value is sent in Authorization and signs nothing.
To route through Hookdeck, create a Top.gg source with the whs_ secret and save its URL on the Webhooks page. For local development:
npx hookdeck-cli listen 3000 top-gg --path /webhooks/top-gg
Securing Top.gg webhooks
x-topgg-signature has the form t={unix timestamp},v1={signature}. The signature is the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the whole whs_ secret. Don't strip the prefix or decode the secret.
Top.gg's own TypeScript sample passes the two digests straight to timingSafeEqual, which throws when a malformed header gives a different length. Check the length and hex format first, as the verifier below does. Top.gg doesn't document a tolerance for t, so the verifier doesn't enforce one.
Node.js verification
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['x-topgg-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const parts = signature.split(',').map((part) => part.trim());
const times = parts.filter((part) => part.startsWith('t=')).map((part) => part.slice(2));
if (times.length !== 1 || !/^[0-9]+$/.test(times[0])) return false;
const message = Buffer.concat([Buffer.from(`${times[0]}.`, 'utf8'), rawBody]);
const candidates = parts.filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
The handler deduplicates on the vote ID and credits the voter with the vote's weight. A webhook.test is acknowledged without any reward.
const express = require('express');
const app = express();
app.post('/webhooks/top-gg', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.TOPGG_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
let event;
try {
event = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!event || typeof event !== 'object' || Array.isArray(event)) return res.sendStatus(400);
if (typeof event.type !== 'string') return res.sendStatus(400);
if (event.type !== 'vote.create') return res.sendStatus(200);
const vote = event.data && typeof event.data === 'object' ? event.data : null;
const voter = vote && vote.user && typeof vote.user === 'object' ? vote.user : null;
if (!vote || typeof vote.id !== 'string' || !voter) return res.sendStatus(400);
try {
if (await alreadyHandled(vote.id)) return res.sendStatus(200);
await queue.add('topgg-vote', {
voteId: vote.id,
discordUserId: voter.platform_id,
weight: vote.weight === 2 ? 2 : 1,
expiresAt: vote.expires_at,
});
await markHandled(vote.id);
} catch {
return res.sendStatus(503);
}
res.sendStatus(200);
});
queue, alreadyHandled and markHandled are placeholders for your queue and dedupe storage. Give out the reward in the worker, not before responding.
Hookdeck's Top.gg source checks the v1 signature. It returns 200 to Top.gg and records any mismatch as failed verification. Hookdeck applies no window to t.
Make Top.gg webhooks production-ready. Hookdeck Event Gateway accepts each vote within Top.gg's 5-second limit and keeps retrying your bot's backend for far longer than Top.gg's few seconds of retries.
Top.gg webhook limitations and pain points
v1 retries last seconds
The Problem: A restart or brief outage loses votes, and voters miss their rewards.
Why It Happens: v1 retries at most 3 times, about 1, 2 and 4 seconds apart, and only for timeouts and 5xx responses.
Workarounds:
- Run the webhook receiver separately from the Discord bot process, so bot restarts don't drop votes.
- Log the
x-topgg-traceID of failed requests so you can raise them with Top.gg support.
How Hookdeck Can Help: Hookdeck acknowledges the vote immediately, then retries your service for as long as your policy allows.
A 5-second timeout
The Problem: Handlers that update a database and send a Discord message before responding can time out and get retried.
Why It Happens: Top.gg treats a response slower than 5 seconds as a failure.
Workarounds:
- Queue the vote and respond first.
- Deduplicate on
data.id, so a slow success that triggers a retry doesn't reward twice.
How Hookdeck Can Help: Hookdeck answers Top.gg at once and gives your service its own, longer timeout.
Two systems with different shapes
The Problem: Code written for v0 bodies (bot, user, isWeekend) breaks on v1, and v0 requests fail signature checks.
Why It Happens: v1 replaced the flat, unsigned v0 format, but both are still documented.
Workarounds:
- Move to v1 by saving the URL on the project's Webhooks page and using the
whs_secret. - Read
data.weightinstead ofisWeekend.
How Hookdeck Can Help: Hookdeck's Top.gg source verifies v1 requests and records unsigned v0 requests as failed, so you can see if any old webhook is still sending.
No documented timestamp tolerance
The Problem: It isn't clear how old a t value you should accept.
Why It Happens: The signature includes t, but Top.gg doesn't say how fresh it should be or whether retries keep the original value.
Workarounds:
- Rely on deduplication by vote ID rather than a tight time window.
- If you add a window, make it generous and log rejections first.
How Hookdeck Can Help: Hookdeck applies no time window and keeps the original headers, so retries and replays still verify.
Best practices
Reward from the worker
Credit the user, then send any Discord message, after the request is acknowledged. Processing webhooks asynchronously explains the pattern.
Use data.id for idempotency
Each vote has a snowflake ID. Store it before granting anything, as in the idempotency guide.
Use expires_at for reminders
data.expires_at says when the user can vote again, which is the right time for a vote reminder.
Pass context through the vote URL
Query parameters on /:id/vote come back in data.query, so you can tag votes by campaign or source.
Conclusion
Top.gg v1 webhooks send vote.create and webhook.test, signed with t= and v1= in x-topgg-signature and keyed by a whs_ secret. Respond within 5 seconds, deduplicate on the vote ID, and don't rely on Top.gg's retries, which end within seconds.
Hookdeck Event Gateway verifies Top.gg votes and holds them until your bot's backend has processed them.
Get started with Hookdeck for free and handle Top.gg webhooks reliably in minutes.