# Top.gg Webhooks

## When to Use This Skill

* How do I receive Top.gg vote webhooks for my Discord bot or server?
* How do I verify the `x-topgg-signature` header?
* How do I handle `vote.create` and `webhook.test` events?
* Why is my Top.gg webhook signature verification failing?
* Why do my legacy (v0) Top.gg webhooks have no signature?

## Verification (core)

Top.gg signs v1 webhooks with an `x-topgg-signature` header of the form `t=<unix seconds>,v1=<hex>`. `v1` is the lowercase hex HMAC-SHA256 of `"<t>.<raw body bytes>"`, keyed with the project's webhook secret (starts with `whs_`, used **whole** as UTF-8 key bytes: don't strip the prefix or decode it). This is not Standard Webhooks.

Only v1 webhooks, whose secret starts with whs_, are supported. Legacy v0 webhooks aren't signed and fail verification.

* Use `t` exactly as it appears in the header (a string); never parse and re-format it.
* Sign the raw bytes as received. Never decode and re-encode the body or `JSON.parse`/`JSON.stringify` it first.
* Accept the delivery if **any** `v1=` entry matches (e.g. during key rotation); ignore other keys such as `v0`. A header with no `t=` value fails.
* Require exactly 64 hex characters in each `v1` (compare case-insensitively) *before* decoding, then compare in constant time. Never call `Buffer.from(sig, 'hex')` on an unvalidated value; it silently drops bad characters.
* A missing or empty header, a malformed value or a mismatch gets `401`.
* Top.gg sends `t` in Unix seconds. Don't reject old timestamps by default: Hookdeck retries and replays resend the original headers and timestamp, so a fixed window would reject legitimate retries. Opt in with `TOP_GG_WEBHOOK_TOLERANCE_SECONDS` (unset or `0` = off).

```javascript
const crypto = require('crypto');

function verifyTopGg(rawBody /* Buffer */, header, secret, toleranceSeconds = 0) {
  const pairs = (header || '').split(',').map((p) => {
    const s = p.trim(), i = s.indexOf('=');
    return i < 0 ? [s, ''] : [s.slice(0, i), s.slice(i + 1)];
  });
  const t = pairs.find(([k]) => k === 't')?.[1];
  const sigs = pairs.filter(([k, v]) => k === 'v1' && /^[0-9a-f]{64}$/i.test(v)).map(([, v]) => Buffer.from(v.toLowerCase()));
  if (!t || sigs.length === 0) return false;
  if (toleranceSeconds > 0 && (!/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds)) return false;
  const expected = Buffer.from(crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex'));
  return sigs.some((sig) => crypto.timingSafeEqual(sig, expected)); // all 64 bytes
}

```

Top.gg's docs show a JavaScript snippet but no verification SDK, so verification is manual in every framework. In Express, read the raw body with `express.raw({ type: '*/*' })` so any content type verifies (Next.js: `await request.arrayBuffer()`; FastAPI: `await request.body()`), and parse JSON only after the check. After verifying, treat every field of the body as untrusted and check types before reading into nested objects.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/top-gg-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/top-gg-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/top-gg-webhooks/examples/fastapi/).

## Common Event Types

Dispatch on the body's top-level `type`; the event data is under `data`. v1 has two event types:

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `vote.create` | A user votes for your project | Reward voters, update leaderboards (`data.weight` is `2` during weekend multipliers; deduplicate on `data.id`) |
| `webhook.test` | You send a test from the project's Webhooks page | Check your endpoint and secret before real votes arrive |

Log and acknowledge any other `type`. Legacy v0 bodies use different values (`upvote`, `test`) and flat fields; see [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/top-gg-webhooks/references/overview.md).

## Environment Variables

```bash
TOP_GG_WEBHOOK_SECRET=whs_xxxxx            # Generated by Top.gg when you save the webhook URL
TOP_GG_WEBHOOK_TOLERANCE_SECONDS=0         # Optional replay window; unset or 0 = off

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 top-gg --path /webhooks/top-gg

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/top-gg-webhooks/references/overview.md) - Top.gg webhook concepts, events, payloads, delivery and retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/top-gg-webhooks/references/setup.md) - Configure the webhook and get the `whs_` secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/top-gg-webhooks/references/verification.md) - Signature verification details and gotchas