Webhooks¶

The following section documents everything related to webhooks. Webhooks are currently unavailable in production, and as such you will need to use https://beta.revolt.chat/api as base API url to use webhooks.

Models¶

BaseWebhook¶

Attributes

id
state

Methods

async delete
async edit
async execute
async fetch

class stoat.BaseWebhook(*, state, id)[source]¶

Represents a webhook on Stoat.

This inherits from BaseWebhook.

await delete(*, http_overrides=None, by_token=False)[source]¶

This function is a coroutine.

Deletes the webhook.

Fires WebhookDeleteEvent for all users who can see webhook channel.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
by_token (bool) –
Whether to use webhook token, if possible.

You must have manage_webhooks to provide False.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

NotAuthenticated

The webhook token is invalid. Only applicable when token is provided.
NotFound – Possible values for type:

Value

Reason

NotFound

The webhook was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await edit(*, http_overrides=None, by_token=False, name=UNDEFINED, avatar=UNDEFINED, permissions=UNDEFINED)[source]¶

This function is a coroutine.

Edits the webhook.

Fires WebhookUpdateEvent for all users who can see webhook channel.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
by_token (bool) –
Whether to use webhook token, if possible.

You must have manage_webhooks to provide False.
name (UndefinedOr[str]) – The new webhook name. Must be between 1 and 32 chars long.
avatar (UndefinedOr[Optional[ResolvableResource]]) – The new webhook avatar.
permissions (UndefinedOr[Permissions]) – The new webhook permissions.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

NotAuthenticated

The webhook token is invalid. Only applicable when by_token is True.
NotFound – Possible values for type:

Value

Reason

NotFound

The webhook/file was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated webhook.

Return type:

Webhook

await execute(content=None, *, http_overrides=None, nonce=None, attachments=None, replies=None, embeds=None, masquerade=None, interactions=None, silent=None, mention_everyone=None, mention_online=None)[source]¶

This function is a coroutine.

Executes a webhook.

The webhook must have send_messages to do this.

If message mentions “@everyone” or “@online”, the webhook must have mention_everyone to do that.

If message mentions any roles, the webhook must have mention_roles to do that.

Fires MessageCreateEvent and optionally MessageAppendEvent, both for all users who can see target channel.

Parameters:

webhook (ULIDOr[BaseWebhook]) – The webhook to execute.
token (str) – The webhook token.
content (Optional[str]) – The message content.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
nonce (Optional[str]) – The message nonce.
attachments (Optional[List[ResolvableResource]]) –
The attachments to send the message with.

Webhook must have upload_files to provide this.
replies (Optional[List[Union[Reply, ULIDOr[BaseMessage]]]]) – The message replies.
embeds (Optional[List[SendableEmbed]]) –
The embeds to send the message with.

Webhook must have send_embeds to provide this.
masquerade (Optional[MessageMasquerade]) –
The masquerade for the message.

Webhook must have use_masquerade to provide this.

If MessageMasquerade.color is provided, manage_roles is also required.
interactions (Optional[MessageInteractions]) –
The message interactions.

If MessageInteractions.reactions is provided, react is required.
silent (Optional[bool]) – Whether to suppress notifications or not.
mention_everyone (Optional[bool]) – Whether to mention all users who can see the channel. This cannot be mixed with mention_online parameter.
mention_online (Optional[bool]) – Whether to mention all users who are online and can see the channel. This cannot be mixed with mention_everyone parameter.

Raises:

HTTPException – Possible values for type:

Value	Reason
`EmptyMessage`	The message was empty.
`FailedValidation`	The payload was invalid.
`InvalidFlagValue`	Both `mention_everyone` and `mention_online` were `True`.
`InvalidOperation`	The passed nonce was already used. One of `MessageInteractions.reactions` elements was invalid.
`InvalidProperty`	`MessageInteractions.restrict_reactions` was `True` but `MessageInteractions.reactions` was empty.
`PayloadTooLarge`	The message was too large.
`TooManyAttachments`	You provided more attachments than allowed on this instance.
`TooManyEmbeds`	You provided more embeds than allowed on this instance.
`TooManyReplies`	You were replying to more messages than was allowed on this instance.

Unauthorized – Possible values for type:

Value

Reason

NotAuthenticated

The webhook token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

The webhook do not have the proper permissions to send messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/file/reply/webhook was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went wrong during message creation.

Returns:

The message that was sent.

Return type:

Message

await fetch(*, http_overrides=None, token=None)[source]¶

This function is a coroutine.

Retrieves a webhook.

If webhook token wasn’t given, the library will attempt get webhook with bot/user token.

You must have manage_webhooks to do this.

Note

Due to Stoat limitation, the webhook avatar information will be partial if no token is provided. Fields are guaranteed to be non-zero/non-empty are id and user_id.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
token (Optional[str]) – The webhook token.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

NotAuthenticated

The webhook token is invalid. Only applicable when token is provided.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to retrieve this webhook.
NotFound – Possible values for type:

Value

Reason

NotFound

The webhook was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The retrieved webhook.

Return type:

Webhook

id¶

The ID of the entity.

Type:: str

state¶

The state that controls this entity.

Type:: State

PartialWebhook¶

Attributes

avatar
id
internal_avatar
name
permissions
raw_permissions
state

Methods

async delete
async edit
async execute
async fetch

class stoat.PartialWebhook(*, state, id, name, internal_avatar, raw_permissions)[source]¶

Represents a partial webhook on Stoat.

Unmodified fields will have UNDEFINED as their value.

This inherits from BaseWebhook.

name¶

The new webhook’s name.

Type:: UndefinedOr[str]

internal_avatar¶

The new webhook’s stateless avatar.

Type:: UndefinedOr[Optional[StatelessAsset]]

raw_permissions¶

The new webhook’s permissions raw value.

Type:: UndefinedOr[int]

property avatar[source]¶

The new avatar of the webhook.

Type:: UndefinedOr[Optional[Asset]]

property permissions[source]¶

The new webhook’s permissions.

Type:: UndefinedOr[Permissions]

await delete(*, http_overrides=None, by_token=False)[source]¶

This function is a coroutine.

Deletes the webhook.

Fires WebhookDeleteEvent for all users who can see webhook channel.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
by_token (bool) –
Whether to use webhook token, if possible.

You must have manage_webhooks to provide False.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

NotAuthenticated

The webhook token is invalid. Only applicable when token is provided.
NotFound – Possible values for type:

Value

Reason

NotFound

The webhook was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await edit(*, http_overrides=None, by_token=False, name=UNDEFINED, avatar=UNDEFINED, permissions=UNDEFINED)[source]¶

This function is a coroutine.

Edits the webhook.

Fires WebhookUpdateEvent for all users who can see webhook channel.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
by_token (bool) –
Whether to use webhook token, if possible.

You must have manage_webhooks to provide False.
name (UndefinedOr[str]) – The new webhook name. Must be between 1 and 32 chars long.
avatar (UndefinedOr[Optional[ResolvableResource]]) – The new webhook avatar.
permissions (UndefinedOr[Permissions]) – The new webhook permissions.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

NotAuthenticated

The webhook token is invalid. Only applicable when by_token is True.
NotFound – Possible values for type:

Value

Reason

NotFound

The webhook/file was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated webhook.

Return type:

Webhook

This function is a coroutine.

Executes a webhook.

The webhook must have send_messages to do this.

If message mentions “@everyone” or “@online”, the webhook must have mention_everyone to do that.

If message mentions any roles, the webhook must have mention_roles to do that.

Fires MessageCreateEvent and optionally MessageAppendEvent, both for all users who can see target channel.

Parameters:

webhook (ULIDOr[BaseWebhook]) – The webhook to execute.
token (str) – The webhook token.
content (Optional[str]) – The message content.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
nonce (Optional[str]) – The message nonce.
attachments (Optional[List[ResolvableResource]]) –
The attachments to send the message with.

Webhook must have upload_files to provide this.
replies (Optional[List[Union[Reply, ULIDOr[BaseMessage]]]]) – The message replies.
embeds (Optional[List[SendableEmbed]]) –
The embeds to send the message with.

Webhook must have send_embeds to provide this.
masquerade (Optional[MessageMasquerade]) –
The masquerade for the message.

Webhook must have use_masquerade to provide this.

If MessageMasquerade.color is provided, manage_roles is also required.
interactions (Optional[MessageInteractions]) –
The message interactions.

If MessageInteractions.reactions is provided, react is required.
silent (Optional[bool]) – Whether to suppress notifications or not.
mention_everyone (Optional[bool]) – Whether to mention all users who can see the channel. This cannot be mixed with mention_online parameter.
mention_online (Optional[bool]) – Whether to mention all users who are online and can see the channel. This cannot be mixed with mention_everyone parameter.

Raises:

HTTPException – Possible values for type:

Value	Reason
`EmptyMessage`	The message was empty.
`FailedValidation`	The payload was invalid.
`InvalidFlagValue`	Both `mention_everyone` and `mention_online` were `True`.
`InvalidOperation`	The passed nonce was already used. One of `MessageInteractions.reactions` elements was invalid.
`InvalidProperty`	`MessageInteractions.restrict_reactions` was `True` but `MessageInteractions.reactions` was empty.
`PayloadTooLarge`	The message was too large.
`TooManyAttachments`	You provided more attachments than allowed on this instance.
`TooManyEmbeds`	You provided more embeds than allowed on this instance.
`TooManyReplies`	You were replying to more messages than was allowed on this instance.

Unauthorized – Possible values for type:

Value

Reason

NotAuthenticated

The webhook token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

The webhook do not have the proper permissions to send messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/file/reply/webhook was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went wrong during message creation.

Returns:

The message that was sent.

Return type:

Message

await fetch(*, http_overrides=None, token=None)[source]¶

This function is a coroutine.

Retrieves a webhook.

If webhook token wasn’t given, the library will attempt get webhook with bot/user token.

You must have manage_webhooks to do this.

Note

Due to Stoat limitation, the webhook avatar information will be partial if no token is provided. Fields are guaranteed to be non-zero/non-empty are id and user_id.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
token (Optional[str]) – The webhook token.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

NotAuthenticated

The webhook token is invalid. Only applicable when token is provided.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to retrieve this webhook.
NotFound – Possible values for type:

Value

Reason

NotFound

The webhook was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The retrieved webhook.

Return type:

Webhook

id¶

The ID of the entity.

Type:: str

state¶

The state that controls this entity.

Type:: State

Webhook¶

Attributes

avatar
channel
channel_id
creator
creator_as_member
creator_as_user
creator_id
id
internal_avatar
name
permissions
raw_permissions
state
token

Methods

async delete
async edit
async execute
async fetch
def get_channel
def get_creator
def get_creator_as_member
def get_creator_as_user
def locally_update
def to_dict

class stoat.Webhook(*, state, id, name, internal_avatar, creator_id, channel_id, raw_permissions, token)[source]¶

Represents a webhook on Stoat.

This inherits from BaseWebhook.

name¶

The webhook’s name.

Type:: str

internal_avatar¶

The webhook’s stateless avatar.

Type:: Optional[StatelessAsset]

creator_id¶

The user’s ID who created this webhook.

Warning

This is available only since API v0.7.17 and only not from GET /webhooks/{webhook.id} endpoints. The attribute will be empty string if unavailable.

Type:: str

channel_id¶

The channel’s ID the webhook in.

Type:: str

raw_permissions¶

The webhook’s permissions raw value.

Type:: int

token¶

The webhook’s private token.

Type:: Optional[str]

get_creator()[source]¶: Optional[Union[Member, User]]: The user who created this webhook.

get_creator_as_member()[source]¶: Optional[Member]: The user who created this webhook.

get_creator_as_user()[source]¶: Optional[User]: The user who created this webhook.

get_channel()[source]¶: Optional[Union[GroupChannel, TextChannel]]: The channel the webhook belongs to.

await delete(*, http_overrides=None, by_token=False)[source]¶

This function is a coroutine.

Deletes the webhook.

Fires WebhookDeleteEvent for all users who can see webhook channel.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
by_token (bool) –
Whether to use webhook token, if possible.

You must have manage_webhooks to provide False.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

NotAuthenticated

The webhook token is invalid. Only applicable when token is provided.
NotFound – Possible values for type:

Value

Reason

NotFound

The webhook was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await edit(*, http_overrides=None, by_token=False, name=UNDEFINED, avatar=UNDEFINED, permissions=UNDEFINED)[source]¶

This function is a coroutine.

Edits the webhook.

Fires WebhookUpdateEvent for all users who can see webhook channel.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
by_token (bool) –
Whether to use webhook token, if possible.

You must have manage_webhooks to provide False.
name (UndefinedOr[str]) – The new webhook name. Must be between 1 and 32 chars long.
avatar (UndefinedOr[Optional[ResolvableResource]]) – The new webhook avatar.
permissions (UndefinedOr[Permissions]) – The new webhook permissions.

Raises:

HTTPException – Possible values for type:

Value

Reason

FailedValidation

The payload was invalid.
Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

NotAuthenticated

The webhook token is invalid. Only applicable when by_token is True.
NotFound – Possible values for type:

Value

Reason

NotFound

The webhook/file was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated webhook.

Return type:

Webhook

This function is a coroutine.

Executes a webhook.

The webhook must have send_messages to do this.

If message mentions “@everyone” or “@online”, the webhook must have mention_everyone to do that.

If message mentions any roles, the webhook must have mention_roles to do that.

Fires MessageCreateEvent and optionally MessageAppendEvent, both for all users who can see target channel.

Parameters:

webhook (ULIDOr[BaseWebhook]) – The webhook to execute.
token (str) – The webhook token.
content (Optional[str]) – The message content.
http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
nonce (Optional[str]) – The message nonce.
attachments (Optional[List[ResolvableResource]]) –
The attachments to send the message with.

Webhook must have upload_files to provide this.
replies (Optional[List[Union[Reply, ULIDOr[BaseMessage]]]]) – The message replies.
embeds (Optional[List[SendableEmbed]]) –
The embeds to send the message with.

Webhook must have send_embeds to provide this.
masquerade (Optional[MessageMasquerade]) –
The masquerade for the message.

Webhook must have use_masquerade to provide this.

If MessageMasquerade.color is provided, manage_roles is also required.
interactions (Optional[MessageInteractions]) –
The message interactions.

If MessageInteractions.reactions is provided, react is required.
silent (Optional[bool]) – Whether to suppress notifications or not.
mention_everyone (Optional[bool]) – Whether to mention all users who can see the channel. This cannot be mixed with mention_online parameter.
mention_online (Optional[bool]) – Whether to mention all users who are online and can see the channel. This cannot be mixed with mention_everyone parameter.

Raises:

HTTPException – Possible values for type:

Value	Reason
`EmptyMessage`	The message was empty.
`FailedValidation`	The payload was invalid.
`InvalidFlagValue`	Both `mention_everyone` and `mention_online` were `True`.
`InvalidOperation`	The passed nonce was already used. One of `MessageInteractions.reactions` elements was invalid.
`InvalidProperty`	`MessageInteractions.restrict_reactions` was `True` but `MessageInteractions.reactions` was empty.
`PayloadTooLarge`	The message was too large.
`TooManyAttachments`	You provided more attachments than allowed on this instance.
`TooManyEmbeds`	You provided more embeds than allowed on this instance.
`TooManyReplies`	You were replying to more messages than was allowed on this instance.

Unauthorized – Possible values for type:

Value

Reason

NotAuthenticated

The webhook token is invalid.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

The webhook do not have the proper permissions to send messages.
NotFound – Possible values for type:

Value

Reason

NotFound

The channel/file/reply/webhook was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

InternalError

Somehow something went wrong during message creation.

Returns:

The message that was sent.

Return type:

Message

await fetch(*, http_overrides=None, token=None)[source]¶

This function is a coroutine.

Retrieves a webhook.

If webhook token wasn’t given, the library will attempt get webhook with bot/user token.

You must have manage_webhooks to do this.

Note

Due to Stoat limitation, the webhook avatar information will be partial if no token is provided. Fields are guaranteed to be non-zero/non-empty are id and user_id.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
token (Optional[str]) – The webhook token.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

NotAuthenticated

The webhook token is invalid. Only applicable when token is provided.
Forbidden – Possible values for type:

Value

Reason

MissingPermission

You do not have the proper permissions to retrieve this webhook.
NotFound – Possible values for type:

Value

Reason

NotFound

The webhook was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The retrieved webhook.

Return type:

Webhook

id¶

The ID of the entity.

Type:: str

locally_update(data, /)[source]¶

Locally updates webhook with provided data.

Warning

This is called by library internally to keep cache up to date.

Parameters:: data (PartialWebhook) – The data to update webhook with.

state¶

The state that controls this entity.

Type:: State

property avatar[source]¶

The webhook’s avatar.

Type:: Optional[Asset]

property creator[source]¶

The user who created this webhook.

Type:: Union[Member, User]

property creator_as_member[source]¶

The user who created this webhook.

Type:: Member

property creator_as_user[source]¶

The user who created this webhook.

Type:: User

property channel[source]¶

The channel the webhook belongs to.

Type:: Union[GroupChannel, TextChannel]

property permissions[source]¶

The webhook’s permissions.

Type:: Permissions

to_dict()[source]¶: dict: Convert webhook to raw data.

Value	Reason
`InvalidSession`	The current bot/user token is invalid.
`NotAuthenticated`	The webhook token is invalid. Only applicable when `token` is provided.

Value	Reason	Populated attributes
`DatabaseError`	Something went wrong during querying database.	`collection`, `operation`

Value	Reason
`MissingPermission`	The webhook do not have the proper permissions to send messages.

Value	Reason
`NotFound`	The channel/file/reply/webhook was not found.