README

Automatically send beautiful Discord notifications when your Laravel queue jobs fail. Zero configuration needed beyond the webhook URL!

Installation

Install via Composer:

composer require the-trybe/laravel-discord-alerts

Configuration

1. Create a Discord Webhook

1. Open your Discord server
2. Go to Server Settings → Integrations → Webhooks
3. Click New Webhook
4. Name it (e.g., "Laravel Alerts" or whatever~)
5. Select the channel where alerts should be posted
6. Copy the Webhook URL

2. Add Webhook URL to Environment

Add to your .env file:

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/1234567890/abcdefghijklmnopqrstuvwxyz
DISCORD_ALERTS_ENABLED=true

3. Done!

That's it! The package will automatically send Discord alerts when any queue job fails.

Advanced Configuration

Publish the configuration file (optional):

php artisan vendor:publish --tag=discord-alerts-config

This creates config/discord-alerts.php with the following options:

return [
    // Enable/disable alerts
    'enabled' => env('DISCORD_ALERTS_ENABLED', true),

    // Your Discord webhook URL
    'webhook_url' => env('DISCORD_WEBHOOK_URL'),

    // Include full stack trace (useful for debugging)
    'include_stack_trace' => env('DISCORD_INCLUDE_STACK_TRACE', false),

    // Include job payload/properties
    'include_payload' => env('DISCORD_INCLUDE_PAYLOAD', true),

    // Maximum payload length (prevents message overflow)
    'max_payload_length' => env('DISCORD_MAX_PAYLOAD_LENGTH', 500),
];

Environment Variables

All available environment variables:

# Required
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Optional
DISCORD_ALERTS_ENABLED=true                # Enable/disable alerts (default: true)
DISCORD_INCLUDE_STACK_TRACE=false          # Include stack trace (default: false)
DISCORD_INCLUDE_PAYLOAD=true               # Include job data (default: true)
DISCORD_MAX_PAYLOAD_LENGTH=500             # Max payload chars (default: 500)

Usage Examples

Basic Usage

No code changes needed! Just dispatch your jobs as usual:

use App\Jobs\ProcessPodcast;

// Dispatch job normally
ProcessPodcast::dispatch($podcast);

// If the job fails, you'll automatically get a Discord alert

What Information is Included?

Each Discord alert includes:

Always Included:

• Job Class - Full class name of the failed job
• Error Message - Exception message
• Attempts - Number of times job was attempted
• Environment - production/staging/local
• Timestamp - When the failure occurred
• Queue Name - Which queue the job was on
• Connection - Queue connection (redis, database, etc.)
• Server - Hostname or app URL
• Exception Type - Class name of the exception
• Location - File and line where error occurred

Optional (Configurable):

• Job Payload - Job properties and data
• Stack Trace - Full exception stack trace

Environment-Based Colors

Alerts are color-coded based on environment:

• Production - Red (critical)
• Staging - Orange (warning)
• Local/Other - Yellow (info)

Troubleshooting

Not Receiving Alerts?

1. Check webhook URL is set:

   php artisan config:clear
   php artisan tinker
   >>> config('discord-alerts.webhook_url')

2. Check alerts are enabled:

   >>> config('discord-alerts.enabled')

3. Check Laravel logs for any errors:

   tail -f storage/logs/laravel.log

4. Test the webhook directly:

   curl -X POST "YOUR_WEBHOOK_URL" \
     -H "Content-Type: application/json" \
     -d '{"content": "Test message from Laravel"}'

License

The MIT License (MIT). Please see License File for more information.

Credits

• The Trybe Agency
• All Contributors