Webhooks

Attention

In order for webhooks to work, the port you provide to WebhookManager.run() must be accessible, meaning your firewall must allow incoming requests to it.

Note

WebhookManager exposes the internal webserver instance via the WebhookManager.webserver property.

WebhookManager

class topgg.WebhookManager(bot: discord.client.Client)

This class is used as a manager for the Top.gg webhook.

Methods WebhookManager.dbl_webhook() and WebhookManager.dsl_webhook() return a modified version of the object, allowing for method chaining.

Parameters

bot (discord.Client) – The Client object that will be utilized by this manager’s webhook(s) to emit events.

dbl_webhook(route: str = '/dbl', auth_key: str = '') → topgg.webhook.WebhookManager

Helper method that configures a route that listens to bot votes.

Parameters

• route (str) – The route to use for bot votes. Must start with /. Defaults to /dbl.

• auth_key (str) – The Authorization key that will be used to verify the incoming requests. All requests are allowed if this is not set.

Returns

Modified version of the object

Return type

WebhookManager

dsl_webhook(route: str = '/dsl', auth_key: str = '') → topgg.webhook.WebhookManager

Helper method that configures a route that listens to server votes.

Parameters

• route (str) – The route to use for server votes. Must start with /. Defaults to /dsl.

• auth_key (str) – The Authorization key that will be used to verify the incoming requests. All requests are allowed if this is not set.

Returns

Modified version of the object

Return type

WebhookManager

run(port: int) → asyncio.Task[None]

Runs the webhook.

Parameters

port (int) – The port to run the webhook on.

property webserver: aiohttp.web_app.Application

Returns the internal web application that handles webhook requests.

Returns

The internal web application.

Return type

aiohttp.web.Application

async close() → None

Stops the webhook.

Examples

Helper methods:

import discord
import topgg


bot = discord.Client(...)  # Initialize a discord.py client
# WebhookManager helper methods allow method chaining, therefore the lines below are valid
bot.topgg_webhook = topgg.WebhookManager(bot)\
                    .dbl_webhook("/dbl", "dbl_auth")\
                    .dsl_webhook("/dsl", "dsl_auth")

Via the webserver property:

You can utilize the internal aiohttp.web.Application via the WebhookManager.webserver property to add custom routes manually.

import discord
import topgg
from aiohttp import web

dbl_auth = "Your DBL Authorization key"  # Leave empty to allow all requests

bot = discord.Client(...)  # Initialize a discord.py client

async def bot_vote_handler(request):
    auth = request.headers.get("Authorization", "")  # Default value will be empty string to allow all requests
    if auth == dbl_auth:
        # Process the vote and return response code 2xx
        return web.Response(status=200, text="OK")
    # Return code 401 if authorization fails
    # 4xx response codes tell Top.gg services not to retry the request
    return web.Response(status=401, text="Authorization failed")

bot.topgg_webhook = topgg.WebhookManager(bot)
bot.topgg_webhook.webserver.router.add_post(path="/dbl", handler=bot_vote_handler)