Core Concepts
Realtime events
Votes, comments, reviews and ratings with zero delay.
startWebhooks launches a dependency free http server. Point each list dashboard at your address with the list id appended and payloads arrive as typed events instantly.
await lists.startWebhooks();
console.log(lists.webhook.address); // http://localhost:8080/discord-botlists
// give each dashboard:
// https://yourdomain.dev/discord-botlists/top.gg
// https://yourdomain.dev/discord-botlists/botlist.me
lists.on('vote', (vote) => {
vote.listId; // 'top.gg'
vote.voterId; // '160105994217586689'
vote.voterName; // 'someuser'
vote.weight; // 2 on weekend multiplier lists
vote.weekend; // true
vote.isTest; // dashboard test button
vote.query; // { ref: 'partner' }
vote.raw; // untouched original body
});
lists.on('review', (review) => {
review.rating; // 1 to 5 when sent
review.content; // review text
});
lists.on('comment', onComment);
lists.on('rating', onRating);
lists.on('test', (vote) => console.log('test from', vote.listId));
lists.on('statsPosted', (report) => console.log(report.posted, 'lists updated'));
lists.on('error', (error) => console.error(error.message));| Event | Payload | Fired when |
|---|---|---|
vote | UniversalVote | A user votes on any list |
comment | UniversalComment | A comment arrives |
review | UniversalComment | A review arrives |
rating | UniversalComment | A rating arrives |
test | UniversalVote | A list dashboard sends a test |
statsPosted | PostReport | After each postStats fan-out |
status | StatusBoard | After each status refresh |
raw | ParsedWebhook | Every parsed webhook |
request | RequestLog | Every http request received |
error | Error | Bad auth, invalid json, internal errors |
Using your own http framework
// express, fastify, whatever you already run
app.post('/webhooks/:list', (req, res) => {
lists.ingestWebhook(req.params.list, req.body);
res.sendStatus(200);
});TipWebhook payloads are normalized per list using the registry webhook hints: the header each list signs with, the voter id field and whether the list uses an event type field like top.gg v1.