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

Open your Discord server
Go to Server Settings → Integrations → Webhooks
Click New Webhook
Name it (e.g., "Laravel Alerts" or whatever~)
Select the channel where alerts should be posted
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?

Check webhook URL is set:

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

Check alerts are enabled:
```
>>> config('discord-alerts.enabled')
```
Check Laravel logs for any errors:
```
tail -f storage/logs/laravel.log
```

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.

the-trybe / laravel-discord-alerts

Maintainers

Details