# Guide to Top.gg Webhooks: Features and Best Practices

[Top.gg](https://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 are `vote.create` and `webhook.test`.
* **v0 (legacy)** ; not signed. A shared secret you enter in the bot edit form is sent verbatim in the `Authorization` header. Flat bodies with `type` values `upvote` and `test`.

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](https://docs.top.gg/webhooks/overview):

* Respond with a `2xx` within 5 seconds.
* Each request has an `x-topgg-trace` header 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](https://docs.top.gg/webhooks/events):

```json
{
  "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

1. Open your project's dashboard on Top.gg and go to **Webhooks**.
2. Paste your endpoint URL, for example `https://example.com/webhooks/top-gg`, and save.
3. Copy the generated secret, prefix included, and store it as `TOPGG_WEBHOOK_SECRET`.
4. Send a test from the Webhooks page and check that a `webhook.test` arrives.

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:

```bash
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

```javascript
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.

```javascript
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](/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-trace` ID 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.weight` instead of `isWeekend`.

**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](/webhooks/guides/why-implement-asynchronous-processing-webhooks) explains the pattern.

### Use data.id for idempotency

Each vote has a snowflake ID. Store it before granting anything, as in the [idempotency guide](/webhooks/guides/implement-webhook-idempotency).

### 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](https://hookdeck.com) verifies Top.gg votes and holds them until your bot's backend has processed them.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Top.gg webhooks reliably in minutes.