Vote Webhooks

Receive real-time notifications when users vote for your bot or server.

Instead of polling the Check Vote Status endpoint, you can configure a webhook URL. discord.place will send an HTTP POST to your endpoint within seconds of a vote being cast.

Setting Up Your Webhook

1. Open your bot's manage page

   Go to discord.place, navigate to your bot’s listing, and click Manage.

2. Open Webhook Settings

   Select the Webhook Settings tab from the manage page navigation.

3. Enter your webhook URL

   Provide the publicly accessible URL of your HTTP endpoint. discord.place will POST to this URL on every vote.

4. Set a webhook token (optional)

   Enter a secret token. This value will be sent in the Authorization header of every webhook request, allowing your server to verify the request came from discord.place.

   Webhook tokens are not supported for Discord Webhook URLs (discord.com/api/webhooks/...). For Discord Webhooks you can instead set a language field to localize the notification message.
5. Save and test

   Save the settings, then use the Send Test button to fire a test payload to your endpoint and confirm it is reachable.

Webhook Payload

discord.place sends a JSON body with the Content-Type: application/json header on every vote.

Bot Vote

bot · string

The snowflake ID of the bot that was voted for. Present on bot vote webhooks.

user · string · required

The snowflake ID of the user who cast the vote.

test · boolean · required

true when the payload is a test event triggered from the manage page; false for real votes.

{
  "bot": "123456789012345678",
  "user": "987654321098765432",
  "test": false
}

Server Vote

guild · string

The snowflake ID of the server that was voted for. Present on server vote webhooks.

user · string · required

The snowflake ID of the user who cast the vote.

test · boolean · required

true for test events, false for real votes.

{
  "guild": "123456789012345678",
  "user": "987654321098765432",
  "test": false
}

Test Webhook

Test payloads only include user and test: true — no bot or guild field is present:

{
  "user": "987654321098765432",
  "test": true
}

Verifying Requests

If you configured a webhook token, compare the value of the incoming Authorization header against your stored secret before processing the payload:

if (req.headers['authorization'] !== process.env.WEBHOOK_TOKEN) {
  return res.status(401).send('Unauthorized');
}

Retry Policy

If your endpoint returns a response with a status code outside the 200–299 range, discord.place will retry the request up to 3 times with a 5-second delay between each attempt. After all retries are exhausted, delivery stops and the event is not queued again.

Always respond with a 2xx status code (e.g., 200 or 204) as quickly as possible. Do any heavy processing asynchronously after sending the response. If your endpoint consistently fails, webhook delivery will be suspended.

Express.js Handler Example

import express from 'express';

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

app.post('/webhook/vote', (req, res) => {
  // Verify the request came from discord.place
  const token = req.headers['authorization'];
  if (token !== process.env.WEBHOOK_TOKEN) {
    return res.status(401).send('Unauthorized');
  }

  const { bot, guild, user, test } = req.body;

  // Acknowledge immediately to avoid retries
  res.sendStatus(200);

  // Handle test pings
  if (test) {
    console.log('Test webhook received from discord.place');
    return;
  }

  if (bot) {
    // Handle bot vote — e.g., grant a vote reward role
    console.log(`User ${user} voted for bot ${bot}`);
  } else if (guild) {
    // Handle server vote
    console.log(`User ${user} voted for server ${guild}`);
  }
});

app.listen(3000);