Webhook API Reference¶

class topgg.webhook.BoundWebhookEndpoint(manager: topgg.webhook.WebhookManager)[source]¶

A WebhookEndpoint with a WebhookManager bound to it.

You can instantiate this object using the WebhookManager.endpoint() method.

Example

import topgg

webhook_manager = (
    topgg.WebhookManager()
    .endpoint()
    .type(topgg.WebhookType.BOT)
    .route("/dblwebhook")
    .auth("youshallnotpass")
)

# The following are valid.
endpoint.callback(lambda vote_data: print("Receives a vote!", vote_data))

# Used as decorator, the decorated function will become the BoundWebhookEndpoint object.
@endpoint.callback
def endpoint(vote_data: topgg.BotVoteData):
    ...

# Used as decorator factory, the decorated function will still be the function itself.
@endpoint.callback()
def on_vote(vote_data: topgg.BotVoteData):
    ...

endpoint.add_to_manager()

add_to_manager() → topgg.webhook.WebhookManager[source]¶

Adds this endpoint to the webhook manager.

Returns: WebhookManager
Raises: errors.TopGGException – If the object lacks attributes.

auth(auth_: str) → topgg.webhook.T¶

Sets the auth of this endpoint.

Parameters: auth_ (str) – The auth of this endpoint.
Returns: WebhookEndpoint

callback(callback_: Optional[Any] = None) → Any¶

Registers a vote callback, called whenever this endpoint receives POST requests.

The callback can be either sync or async. This method can be used as a decorator or a decorator factory.

Example

import topgg

webhook_manager = topgg.WebhookManager()
endpoint = (
    topgg.WebhookEndpoint()
    .type(topgg.WebhookType.BOT)
    .route("/dblwebhook")
    .auth("youshallnotpass")
)

# The following are valid.
endpoint.callback(lambda vote_data: print("Receives a vote!", vote_data))

# Used as decorator, the decorated function will become the WebhookEndpoint object.
@endpoint.callback
def endpoint(vote_data: topgg.BotVoteData):
    ...

# Used as decorator factory, the decorated function will still be the function itself.
@endpoint.callback()
def on_vote(vote_data: topgg.BotVoteData):
    ...

webhook_manager.endpoint(endpoint)

route(route_: str) → topgg.webhook.T¶

Sets the route of this endpoint.

Parameters: route_ (str) – The route of this endpoint.
Returns: WebhookEndpoint

type(type_: topgg.webhook.WebhookType) → topgg.webhook.T¶

Sets the type of this endpoint.

Parameters: type_ (WebhookType) – The type of the endpoint.
Returns: WebhookEndpoint

class topgg.webhook.WebhookEndpoint[source]¶

A helper class to setup webhook endpoint.

auth(auth_: str) → topgg.webhook.T[source]¶

Sets the auth of this endpoint.

Parameters: auth_ (str) – The auth of this endpoint.
Returns: WebhookEndpoint

callback(callback_: None) → Callable[[Callable[[...], Any]], Callable[[...], Any]][source]¶

callback(callback_: Callable[[...], Any]) → topgg.webhook.T

Registers a vote callback, called whenever this endpoint receives POST requests.

The callback can be either sync or async. This method can be used as a decorator or a decorator factory.

Example

import topgg

webhook_manager = topgg.WebhookManager()
endpoint = (
    topgg.WebhookEndpoint()
    .type(topgg.WebhookType.BOT)
    .route("/dblwebhook")
    .auth("youshallnotpass")
)

# The following are valid.
endpoint.callback(lambda vote_data: print("Receives a vote!", vote_data))

# Used as decorator, the decorated function will become the WebhookEndpoint object.
@endpoint.callback
def endpoint(vote_data: topgg.BotVoteData):
    ...

# Used as decorator factory, the decorated function will still be the function itself.
@endpoint.callback()
def on_vote(vote_data: topgg.BotVoteData):
    ...

webhook_manager.endpoint(endpoint)

route(route_: str) → topgg.webhook.T[source]¶

Sets the route of this endpoint.

Parameters: route_ (str) – The route of this endpoint.
Returns: WebhookEndpoint

type(type_: topgg.webhook.WebhookType) → topgg.webhook.T[source]¶

Sets the type of this endpoint.

Parameters: type_ (WebhookType) – The type of the endpoint.
Returns: WebhookEndpoint

class topgg.webhook.WebhookManager[source]¶

A class for managing Top.gg webhooks.

async close() → None[source]¶: Stops the webhook.

endpoint(endpoint_: None = None) → BoundWebhookEndpoint[source]¶

endpoint(endpoint_: WebhookEndpoint) → WebhookManager

Helper method that returns a WebhookEndpoint object.

Parameters: endpoint_ (typing.Optional [ WebhookEndpoint ]) – The endpoint to add.
Returns: An instance of WebhookManager if endpoint was provided, otherwise BoundWebhookEndpoint.
Return type: typing.Union [ WebhookManager, BoundWebhookEndpoint ]
Raises: TopGGException – If the endpoint is lacking attributes.

get_data(type_: Any, default: Optional[Any] = None) → Any¶: Gets the injected data.

set_data(data_: Any, *, override: bool = False) → topgg.data.DataContainerT¶

Sets data to be available in your functions.

Parameters

data_ (typing.Any) – The data to be injected.
override (bool) – Whether or not to override another instance that already exists.

Raises

TopGGException – If override is False and another instance of the same type exists.

async start(port: int) → None[source]¶

Runs the webhook.

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

property app: aiohttp.web_app.Application¶

Returns the internal web application that handles webhook requests.

Returns: The internal web application.
Return type: aiohttp.web.Application

property is_running: bool¶: Returns whether or not the webserver is running.

class topgg.webhook.WebhookType(value)[source]¶

An enum that represents the type of an endpoint.

BOT = 1¶: Marks the endpoint as a bot webhook.

GUILD = 2¶: Marks the endpoint as a guild webhook.

topgg.webhook.endpoint(route: str, type: topgg.webhook.WebhookType, auth: str = '') → Callable[[Callable[[...], Any]], topgg.webhook.WebhookEndpoint][source]¶

A decorator factory for instantiating WebhookEndpoint.

Parameters

route (str) – The route for the endpoint.
type (WebhookType) – The type of the endpoint.
auth (str) – The auth for the endpoint.

Returns

The actual decorator.

Return type

typing.Callable [[ typing.Callable […, typing.Any ]], WebhookEndpoint ]

Example

import topgg

@topgg.endpoint("/dblwebhook", WebhookType.BOT, "youshallnotpass")
async def on_vote(
    vote_data: topgg.BotVoteData,
    # database here is an injected data
    database: Database = topgg.data(Database),
):
    ...