Webhook API Reference

toppy.webhook.create_webhook_server(client: ClientProtocol, *, dbl_auth: Optional[str] = ..., dbgg_auth: Optional[str] = ..., topgg_auth: Optional[str] = ..., web_app_class: Type[web.Application] = <class 'aiohttp.web_app.Application'>, application: Optional[web.Application] = None, db: Optional[AbstractDatabase] = None, **kwargs) → web.Application

A webhooks server to receives votes and dispatch them to your bot! Go to your bot’s edit page on Discord Bot List or Top.gg do add the link and authorization.

Use toppy.utils.run_webhook_server() to run the server optionally connect the database.

Parameters

• client (ClientProtocol) – The Discord Bot instance. Any Client derived from discord.Client or any other fork’s Client. It must fit the ClientProtocol.

• dbl_auth (Optional[str]) – The Discord Bot List webhook secret. This can be made in the bot’s edit section.

• dbgg_auth (Optional[str]) – The DiscordBotGG webhook secret. This can be found in the bots vote settings section.

• topgg_auth (Optional[str]) – The Authorization for the webhook. You can make this in the webhooks section of the bot’s edit section.

• web_app_class (Type[aiohttp.web.Application]) – The web application class to use. Must be derived from aiohttp.web.Application. If combined with application this will be ignored.

• application (aiohttp.web.Application) – A pre-existing application to use.

• db (Optional[AbstractDatabase]) – The instance of a database. Must fit the AbstractDatabase protocol.

• **kwargs – Keyword arguments to pass onto web_app_class.

Returns

• The class from web_app_class with the routes added.

• The routes are posts to /dbl, /dbgg, or /topgg.

New in version 1.5: There are now options for a cache.

Payloads

class toppy.webhook.DiscordBotListVotePayload(client: ClientProtocol, data: dict)

A class to represent the a Discord Bot List webhook payload

New in version 1.3.

property admin: bool

If the user is a site administrator for Discord Bot List.

Return type

bool

property avatar: str

The avatar hash of the user.

Return type

str

property username: str

The username of the user who voted.

Return type

str

async fetch() → None

Fetches the user id from the Discord API to ensure user is not None.

property raw: dict

Returns the raw data sent.

Return type

dict

property time: datetime

The time the user voted at.

Return type

datetime.datetime

property user: Optional[Snowflake]

Returns the User object for the user based on what library your client is from. If missing use DiscordBotListVotePayload.fetch().

Return type

Optional[Snowflake]

property user_id: int

The ID of the user who voted.

Return type

int

class toppy.webhook.TopGGVotePayload(client: ClientProtocol, data: dict)

A class to represent the a Top.gg webhook payload

New in version 1.3.

property bot_id: int

Discord ID of the bot that received a vote.

Return type

int

property user_id: int

Discord ID of the user who voted.

Return type

int

property type: Literal['upvote', 'test']

The type of the vote (should always be “upvote” except when using the test button it’s “test”).

Return type

Literal[“upvote”, “test”]

property is_weekend: bool

Whether the weekend multiplier is in effect, meaning users votes count as two.

Return type

bool

property query: Optional[str]

?a=1&b=2.

Return type

str

Type

Query string params found on the /bot/

Type

ID/vote page. Example

property bot: Optional[Snowflake]

Returns the User object for the bot voted for based on what library your client is from. If missing use TopGGVotePayload.fetch()

Return type

Optional[Snowflake]

async fetch() → None

Fetches the user id from the Discord API to ensure TopGGVotePayload.user and TopGGVotePayload.bot are not None.

property raw: dict

Returns the raw data sent.

Return type

dict

property time: datetime

The time the user voted at.

Return type

datetime.datetime

property user: Optional[Snowflake]

Returns the User object for the user based on what library your client is from. If missing use DiscordBotListVotePayload.fetch().

Return type

Optional[Snowflake]

Caching Votes

class toppy.webhook.CachedVote(number: int, id: int, time: datetime, site: str)

A dataclass to represent a generic vote.

number

The number increases by one every time someone votes.

Type

int

id

The ID of the user who voted.

Type

int

time

The time the user voted at.

Type

datetime.datetime

site

The site the user voted on.

Type

str

class toppy.webhook.AbstractDatabase(*args, **kwargs)

A mostly unimplemented class for caching votes.

This documentation is identical the following:

JSONDatabase SQLiteDatabase

New in version 1.5.

async connect() → None

Connect to the database.

async insert(payload: BaseVotePayload) → None

Insert a payload into the database.

Parameters

payload (BaseVotePayload) –

The payload to insert.

Note

This function is usually used internally by in the web application.

abstract async fetchone(number: int) → Optional[CachedVote]

Fetch a vote. Use fetchmany() to fetch multiple votes.

Parameters

number (int) – The number in order from least recent to most recent to fetch.

Return type

Optional[CachedVote]

abstract async fetchmany() → list[CachedVote]

Fetch multiple votes. This will be expanded in the future with filters.

Return type

list[CachedVote]

class toppy.webhook.JSONDatabase

A cache for votes using json.

Warning

JSON is not a proper database and you may have problems with it as your bot grows.

async connect() → None

Connect to the database.

async insert(payload: BaseVotePayload) → None

Insert a payload into the database.

Parameters

payload (BaseVotePayload) –

The payload to insert.

Note

This function is usually used internally by in the web application.

async fetchone(number: int) → Optional[CachedVote]

Fetch a vote. Use JSONDatabase.fetchmany() to fetch multiple votes.

Parameters

number (int) – The number in order from least recent to most recent to fetch.

Return type

Optional[CachedVote]

async fetchmany() → list[CachedVote]

Fetch multiple votes. This will be expanded in the future with filters.

Return type

list[CachedVote]

class toppy.webhook.SQLiteDatabase

A cache for votes using SQLite.

async connect() → None

Connect to the database.

async insert(payload: BaseVotePayload) → None

Insert a payload into the database.

Parameters

payload (BaseVotePayload) –

The payload to insert.

Note

This function is usually used internally by in the web application.

async fetchone(number: int) → Optional[CachedVote]

Fetch a vote. Use SQLDatabase.fetchmany() to fetch multiple votes.

Parameters

number (int) – The number in order from least recent to most recent to fetch.

Return type

Optional[CachedVote]

async fetchmany() → list[CachedVote]

Fetch multiple votes. This will be expanded in the future with filters.

Return type

list[CachedVote]

Event Reference

toppy.webhook.on_dbl_vote(payload)

This is called when you have a webhook server made with create_webhook_server() and someone votes for your bot on Discord Bot List.

Parameters

payload (DiscordBotListVotePayload) – The payload with the vote information.

toppy.webhook.on_topgg_vote(payload)

This is called when you have a webhook server made with create_webhook_server() and someone votes for your bot on Top.gg.

Parameters

payload (TopGGVotePayload) – The payload with the vote information.