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-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).
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:

EventTriggered WhenCommon Use Cases
vote.createA user votes for your projectReward voters, update leaderboards (data.weight is 2 during weekend multipliers; deduplicate on data.id)
webhook.testYou send a test from the project's Webhooks pageCheck 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →