Registry / communication / discord-webhook

discord-webhook

library1.4.1pypypi✓ verified 24d ago

discord-webhook is a Python library designed to easily send Discord webhooks. It simplifies the process of sending messages, embeds, files, and managing webhook interactions with Discord's API. The current version is 1.4.1, and it maintains an active development cycle with frequent updates addressing features, fixes, and occasionally breaking changes.

communication

pip install discord-webhook

github ↗package ↗

INSTALL

IMPORT

SIG · DISCORD-WEBHOOK

discord-webhook

communicationpythonv1.4.1

Install

2.4s avg

Import

493ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.510s · 21.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.476s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DiscordWebhook

✓ from discord_webhook import DiscordWebhook

DiscordEmbed

✓ from discord_webhook import DiscordEmbed

AsyncDiscordWebhook

✓ from discord_webhook import AsyncDiscordWebhook

For asynchronous operations, use AsyncDiscordWebhook.

This quickstart demonstrates how to send a Discord webhook with an embedded message. It retrieves the webhook URL from an environment variable, constructs a `DiscordEmbed` with a title, description, color, fields, footer, and timestamp, then adds it to a `DiscordWebhook` instance and executes it. Remember to set the `DISCORD_WEBHOOK_URL` environment variable.

import os from discord_webhook import DiscordWebhook, DiscordEmbed webhook_url = os.environ.get('DISCORD_WEBHOOK_URL', '') if webhook_url: webhook = DiscordWebhook(url=webhook_url) # Create an embed embed = DiscordEmbed( title='New Event Alert', description='A new event has been scheduled. Check it out!', color='03b2f8' # Hex color without the # ) # Add fields to the embed embed.add_embed_field(name='Event Name', value='Python Dev Meetup') embed.add_embed_field(name='Date', value='2025-08-01', inline=True) embed.add_embed_field(name='Time', value='19:00 UTC', inline=True) # Set footer and timestamp embed.set_footer(text='Powered by discord-webhook') embed.set_timestamp() # Add the embed to the webhook webhook.add_embed(embed) # Execute the webhook try: response = webhook.execute() print(f"Webhook sent successfully. Status: {response.status_code}") except Exception as e: print(f"Failed to send webhook: {e}") else: print("DISCORD_WEBHOOK_URL environment variable not set. Skipping webhook send.")

Debug

Known issues

breakingIn version 1.0.0, the `url` parameter for `DiscordWebhook` and `AsyncDiscordWebhook` was restricted to accept only a single URL string. Additionally, the `.edit()` and `.delete()` methods no longer accept parameters.

fix

Ensure `url` is a single string. For `.edit()` and `.delete()`, call them without arguments after the webhook has been executed and its ID populated.

affects: >=1.0.0

breakingVersion 1.0.0 renamed `DiscordEmbed.del_embed_field()` to `DiscordEmbed.delete_embed_field()`.

fix

Update calls from `del_embed_field()` to `delete_embed_field()`.

affects: >=1.0.0

breakingVersion 1.1.0 removed `remove_files` as an optional parameter from the `.execute()` method. Files are now automatically cleared after execution to prevent accidental re-upload on subsequent edits.

fix

Remove the `remove_files` parameter from `.execute()` calls. The library now handles file clearing automatically.

affects: >=1.1.0

breakingIn version 0.17.0, `ColourNotInRangeException` was renamed to `ColorNotInRangeException` for consistency.

fix

Update any exception handling or imports of `ColourNotInRangeException` to `ColorNotInRangeException`.

affects: >=0.17.0

gotchaBefore version 1.2.1, using the `timeout` keyword argument could accidentally set `tts` (text-to-speech) to true due to a bug.

fix

Upgrade to version 1.2.1 or newer. If stuck on an older version, explicitly set `tts=False` when using `timeout` if TTS is not desired.

affects: <1.2.1

gotchaThe `set_timestamp()` method's accepted types for timestamps evolved. Version 1.2.0 added support for `datetime` objects, and 1.4.0 added support for string representations.

fix

For full flexibility, ensure you are on version 1.4.0 or newer if passing strings. Otherwise, provide `datetime` objects for versions >=1.2.0, or rely on automatic timestamp generation if no argument is passed.

affects: <1.4.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'discord_webhook'

The `discord-webhook` package is not installed or not accessible in the current Python environment.

fix

Install the package using pip: `pip install discord-webhook`

{"message": "Unknown Webhook", "code": 10015}

This error is returned by Discord's API, indicating that the provided webhook URL is incorrect, expired, or the webhook itself has been deleted on Discord.

fix

Verify that the webhook URL is correctly copied from Discord, is still active, and has not been deleted. Create a new webhook if necessary and update your code with the new URL.

400 Bad Request

This HTTP status code indicates that the request sent to Discord's API was malformed or missing required parameters, such as attempting to send an empty message without any content, embeds, or files.

fix

Ensure that your `DiscordWebhook` object or its `execute()` method includes valid `content`, `embeds`, or `files` parameters. For example, `webhook = DiscordWebhook(url='YOUR_WEBHOOK_URL', content='Your message here')`.

403 Forbidden

This HTTP status code typically means the webhook lacks the necessary permissions to post in the specified channel, is being rate-limited by Discord, or the webhook token/URL is invalid or unauthorized.

fix

Check the webhook's permissions in Discord (ensure it can send messages in the channel). If rate-limited, the library's `rate_limit_retry=True` (default) should handle it, but excessive requests might still lead to this. Verify the webhook URL again for any errors.

AttributeError: 'DiscordEmbed' object has no attribute 'send'

The `send()` or `execute()` method belongs to the `DiscordWebhook` object, not the `DiscordEmbed` object. Embeds must be added to a webhook object before the webhook can be sent.

fix

Add the `DiscordEmbed` object to the `DiscordWebhook` object using `add_embed()` and then call `execute()` on the `DiscordWebhook` object.

Upgrade

Version history

1.4.1latest on PyPI · released Mar 5, 2025

Audit

Dependencies

requestsrequiredUsed for making HTTP requests to the Discord API.

Agent activity

32 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lovvskillz/python-discord-webhook ↗

packagehttps://pypi.org/project/discord-webhook/ ↗