Webhooks

Guide to how Webhooks work.

Overview

Webhooks is a service provided by discordlist.space that notifies you of any trigger completed on a bot or server that you own. These notifications are sent in the form of a GET/POST request with a payload that contains data of what action was completed. These are useful for receiving listing upvotes and rewarding users.

Setup

Webhooks can be set up by visiting the dashboard of your bot or server. Simply go to your bot/server page, click on Dashboard, and click Webhooks on the menu on the left. Select the appropriate triggers and fill in the additional information and the system will begin fulfilling webhook requests immediately. It is recommended that you have separate endpoints for each bot or server that you own.

Authentication

Proper authentication is important when using webhooks. Remember to keep your webhook URL secret as exposing it could have unforeseen consequences on your end. The token you provide during the new webhook form will be sent during every webhook request as the Authorization header. Compare this header value to the same token you provided to ensure that discordlist.space is the origin of the request and not a foreign entity.

Use Cases

Webhooks can be useful in several situations, especially for upvote rewards. Here are some examples of use cases for webhooks:

  • Give users some virtual currency after upvoting the bot

  • Give users a badge after posting a review of the bot

  • Post a log in a channel after the bot is invited

Triggers

Webhook triggers are the reason for a webhook being executed. Multiple triggers may be assigned to the same webhook if necessary. The following triggers are supported by our service:

Trigger Code

Listing Type

Description

upvote

Bots, servers

When a user has upvoted the listing

review

Bots, servers

When a user has posted a new review on the listing

botInvite

Bots

When a user clicked the invite button on the bot page (note: this does not mean the bot was successfully invited to a server)

serverJoin

Servers

When a user clicked the join button on the server page (note: this does not mean the user successfully joined the server)

Upvote

An upvote trigger is useful for rewarding users with a virtual currency or another reward type. Users upvoting means that your bot will receive a small boost in position on the listing. This generally means that you will receive more invites since your bot listing will get more exposure.

body-data.json
{
"trigger": "upvote",
"bot": { ... }, // property only exists for bot listings
"server": { ... }, // property only exists for server listings
"user": {
"id": "507329700402561045",
"username": "PassTheMayo",
"discriminator": "8620",
"avatar": "40a90f6677bd37e777280fa549a78e5f",
"shortDescription": "",
"banned": null,
"admin": true,
"donator": true,
"createdAt": 1623854559629,
"updatedAt": 1625171116320
},
"timestamp": 1625528837373
}

Review

Review webhooks are sent after a user has posted a review on your bot or server listing page. The body data of the webhook will also contain information about the review itself.

body-data.json
{
"trigger": "review",
"bot": { ... }, // property only exists for bot listings
"server": { ... }, // property only exists for server listings
"user": {
"id": "507329700402561045",
"username": "PassTheMayo",
"discriminator": "8620",
"avatar": "40a90f6677bd37e777280fa549a78e5f",
"shortDescription": "",
"banned": false,
"admin": true,
"donator": true,
"createdAt": 1623854559629,
"updatedAt": 1625171116320
},
"timestamp": 1625529515096
}

Bot Invite

This is sent whenever a user (whether logged in or not) has clicked the invite button on your bot listing page. This does not guarantee that the user successfully invited the bot to the server.

body-data.json
{
"trigger": "botInvite",
"bot": { ... },
"user": {
"id": "507329700402561045",
"username": "PassTheMayo",
"discriminator": "8620",
"avatar": "40a90f6677bd37e777280fa549a78e5f",
"shortDescription": "",
"banned": false,
"admin": true,
"donator": true,
"createdAt": 1623854559629,
"updatedAt": 1625171116320
},
"timestamp": 1625529515096
}

Server Join

This is sent whenever a user (whether logged in or not) has clicked the join button on your server listing page. This does not guarantee that the user successfully joined the server.

body-data.json
{
"trigger": "serverJoin",
"server": { ... },
"user": {
"id": "507329700402561045",
"username": "PassTheMayo",
"discriminator": "8620",
"avatar": "40a90f6677bd37e777280fa549a78e5f",
"shortDescription": "",
"banned": false,
"admin": true,
"donator": true,
"createdAt": 1623854559629,
"updatedAt": 1625171116320
},
"timestamp": 1625529515096
}

Discord Webhooks

You may also provide a Discord webhook URL in place of your own webhook URL. We will properly format and send an embed with information about the action. This is useful if you only want to use webhooks to see who upvoted, invited, or posted a review of your bot or server in a Discord channel.