DRF Discord Handler

A Django REST Framework package that automatically sends detailed exception notifications to Discord channels when errors occur in your API.

Links

• PyPI: https://pypi.org/project/drf-discord-handler/
• GitHub: https://github.com/shinkeonkim/drf_discord_handler

Features

• 🚨 Automatic Exception Notifications: Automatically sends detailed exception information to Discord when errors occur in your DRF API
• 📊 Rich Error Details: Includes request method, path, full URL, user information, device info, stack traces, and more
• 🔒 Sensitive Data Filtering: Automatically filters sensitive information (passwords, tokens, etc.) before sending to Discord
• 🧵 Discord Thread Support: Creates threads in Discord forum channels for better organization of error messages
• ⚙️ Configurable: Easy configuration through Django settings
• 🎯 Multiple Channels: Support for different Discord channels for different types of notifications

Screenshots

Installation

Install the package using pip:

pip install drf-discord-handler

Or using uv:

uv add drf-discord-handler

Requirements

• Python 3.14+
• Django 6.0+
• Django REST Framework 3.16.1+

Quick Start

1. Configure Discord Webhook

Add the following configuration to your Django settings.py:

DRF_DISCORD_HANDLER = {
    'ENABLED': True,
    'EXCEPTION_WEBHOOK_URL': 'https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN',
    'FILTER_SENSITIVE_DATA': True,
    'EXCLUDE_EXCEPTIONS': [
        # django.http.Http404,  # Example: exclude 404 errors
    ],
}

2. Configure DRF Exception Handler

Add the exception handler to your DRF settings:

REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'drf_discord_handler.discord_exception_handler',
}

3. That's it!

Now whenever an exception occurs in your DRF API, you'll receive detailed notifications in your Discord channel.

Configuration Options

ENABLED (bool, default: True)

Enable or disable Discord notifications. Set to False to disable notifications (useful for development).

EXCEPTION_WEBHOOK_URL (str, required)

Discord webhook URL for exception notifications. You can create a webhook in your Discord server settings.

FILTER_SENSITIVE_DATA (bool, default: True)

Automatically filter sensitive information (passwords, tokens, etc.) from request data before sending to Discord.

SENSITIVE_KEYS (list, optional)

Custom list of keys to filter. Default includes common sensitive keys like password, token, secret, etc.

EXCLUDE_EXCEPTIONS (list, optional)

List of exception classes to exclude from Discord notifications. For example, to exclude 404 errors:

'EXCLUDE_EXCEPTIONS': [
    django.http.Http404,
]

What Information is Sent?

When an exception occurs, the following information is automatically sent to Discord:

• Exception Details: Exception type and message
• Request Information: HTTP method, path, full URL, URL pattern
• User Information: User ID, username, email (if authenticated), or "Anonymous" if not
• Device Information: User-Agent, IP address, browser, OS
• View Information: View class and view name
• Request Details: Query parameters, request body, headers
• Response Details: Status code and response data
• Stack Trace: Full stack trace with local variables (sent in separate messages/threads)

Discord Thread Support

If your Discord webhook is configured for a forum channel, the package automatically creates threads for each exception. The full stack trace is sent in the thread, keeping the main channel clean.

Using DiscordClient Directly

You can also use the DiscordClient class directly to send custom messages:

from drf_discord_handler import DiscordClient

client = DiscordClient(webhook_url='https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN')

# Send a simple message
client.send_message(content="Hello from Django!")

# Send an embed
client.send_embed(
    title="Custom Notification",
    description="This is a custom notification",
    color=0x00FF00,  # Green color
)

Security Considerations

• Sensitive Data Filtering: By default, the package filters sensitive information from request data. Make sure FILTER_SENSITIVE_DATA is set to True in production.
• Webhook URLs: Keep your Discord webhook URLs secure. Never commit them to version control. Use environment variables instead:

import os

DRF_DISCORD_HANDLER = {
    'EXCEPTION_WEBHOOK_URL': os.environ.get('DISCORD_EXCEPTION_WEBHOOK_URL'),
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Support

If you encounter any issues or have questions, please open an issue on GitHub.