Skip to main content
Use vote webhooks when you want Rankly to notify your service about verified votes.

​
Vote webhook

Use this for voter rewards, role grants, or vote analytics.

​
What Rankly sends

When a vote is processed, Rankly posts a small JSON payload to the webhook URL saved on the server. Example payload: 
{
  "userId": "123456789012345678",
  "serverId": "987654321098765432",
  "timestamp": "2026-01-01T12:00:00.000Z",
  "creditsAwarded": true,
  "adBlocker": false,
  "creditDenialReason": null
}
A test delivery uses the same shape and may include test: true.

​
Set it up

1

Use a public HTTPS endpoint

Your webhook must be reachable over HTTPS. Localhost and private/internal addresses are rejected.
2

Save the URL in Rankly

Add the endpoint in your server settings, then optionally set an Authorization header if your backend expects one.
3

Send a test request

Use the dashboard test action before relying on live vote traffic.
4

Return 2xx quickly

Acknowledge the request fast and do your heavier work asynchronously.

​
Example receiver

import express from 'express';

const app = express();
app.use(express.json());

app.post('/rankly/vote', async (req, res) => {
  const auth = req.header('Authorization');
  if (auth !== `Bearer ${process.env.RANKLY_WEBHOOK_SECRET}`) {
    return res.status(401).json({ error: 'unauthorized' });
  }

  const { userId, serverId, creditsAwarded, creditDenialReason } = req.body;

  // Update your database or trigger a reward here.
  console.log({ userId, serverId, creditsAwarded, creditDenialReason });

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

​
Security notes

  • Keep the endpoint public, but keep the processing logic private.
  • Verify the Authorization header if you set one in Rankly.
  • Treat deliveries as at-least-once and dedupe by userId, serverId, and timestamp.
  • Never point a webhook at localhost, a private subnet, or an internal admin panel.

​
Common issues

  • No delivery at all: check the saved URL and whether the test request succeeds.
  • 4xx response: fix your endpoint auth or JSON parsing.
  • Repeated events: add deduplication before issuing rewards.
  • No credits awarded: the vote may still be counted, but the payload will explain why credits were denied.

Server Premium Webhooks

Handle signed monetization events for server premium purchases.