Discord Webhook

1.4.1 · active · verified Sun Apr 12

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.

Warnings

breaking In 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.
breaking Version 1.0.0 renamed `DiscordEmbed.del_embed_field()` to `DiscordEmbed.delete_embed_field()`.
Fix: Update calls from `del_embed_field()` to `delete_embed_field()`.
breaking Version 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.
breaking In version 0.17.0, `ColourNotInRangeException` was renamed to `ColorNotInRangeException` for consistency.
Fix: Update any exception handling or imports of `ColourNotInRangeException` to `ColorNotInRangeException`.
gotcha Before 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.
gotcha The `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.

Install

pip install discord-webhook Install stable version

Imports

DiscordWebhook

from discord_webhook import DiscordWebhook

DiscordEmbed

from discord_webhook import DiscordEmbed

AsyncDiscordWebhook
```
from discord_webhook import AsyncDiscordWebhook
```
For asynchronous operations, use AsyncDiscordWebhook.

Quickstart

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.")

view raw JSON →