Skip to main content
Use this guide when you want Rankly to push vote events to your bot or backend.

​
What the webhook contains

Rankly sends a signed JSON payload that looks like this: 
{
  "event": "bot_vote",
  "timestamp": "2026-01-01T12:00:00.000Z",
  "voter": {
    "userId": "123456789012345678",
    "username": "Skyline"
  },
  "bot": {
    "id": "987654321098765432",
    "name": "Rankly Bot"
  },
  "creditsAwarded": true,
  "adBlocker": false,
  "creditDenialReason": null
}
The signature is sent in the X-Webhook-Signature header.

​
How to handle it

1

Expose a public HTTPS endpoint

The endpoint must be reachable from the public internet.
2

Verify the signature

Recompute the HMAC with your webhook secret and compare it to the X-Webhook-Signature header.
3

Deduplicate events

Treat the webhook as at-least-once delivery and ignore duplicates by storing a stable event fingerprint.
4

Respond quickly

Return a 2xx response before you do slow work like database updates or role grants.

​
Example verification

import crypto from 'crypto';
import express from 'express';

const app = express();
app.use(express.json({
  verify: (req, _res, buf) => {
    req.rawBody = buf.toString('utf8');
  }
}));

app.post('/rankly/bot-vote', async (req, res) => {
  const receivedSignature = req.header('X-Webhook-Signature');
  const expectedSignature = crypto
    .createHmac('sha256', process.env.RANKLY_WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest('hex');

  if (receivedSignature !== expectedSignature) {
    return res.status(401).json({ error: 'invalid signature' });
  }

  const { voter, bot, creditsAwarded, creditDenialReason } = req.body;

  // Grant rewards, log the vote, or update your internal state here.
  console.log({ voter, bot, creditsAwarded, creditDenialReason });

  return res.status(200).json({ received: true });
});

​
What to build with it

  • Reward a voter inside your bot
  • Log the vote in a moderation channel
  • Update a dashboard badge or vote count
  • Trigger a lightweight analytics event

​
Security notes

  • Keep the secret private and rotate it if it leaks.
  • Verify the exact payload you received, not a re-serialized version that may change formatting.
  • Use a unique event key to avoid double rewards.
  • Do not expose your webhook endpoint with destructive actions on the first request.

Bot API Integration

Read data on demand when a webhook is not necessary.

Public API Reference

Pull server and vote state directly from Rankly.