Agent skill
Top.gg Webhooks Skill
Receive and verify Top.gg (top.gg) webhooks. Use when setting up Top.gg vote webhook endpoints for Discord bots and servers, debugging x-topgg-signature verification, or handling vote.create and webhook.test events.
Install this skill
npx skills add hookdeck/webhook-skills --skill 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-signatureheader? - How do I handle
vote.createandwebhook.testevents? - 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
texactly 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.stringifyit first. - Accept the delivery if any
v1=entry matches (e.g. during key rotation); ignore other keys such asv0. A header with not=value fails. - Require exactly 64 hex characters in each
v1(compare case-insensitively) before decoding, then compare in constant time. Never callBuffer.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
tin 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 withTOP_(unset orGG_ WEBHOOK_ TOLERANCE_ SECONDS 0= off).
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/, examples/nextjs/, 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.
Environment Variables
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
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 top-gg --path /webhooks/top-gg
Reference Materials
- references/overview.md - Top.gg webhook concepts, events, payloads, delivery and retries
- references/setup.md - Configure the webhook and get the
whs_secret - references/verification.md - Signature verification details and gotchas