Discord Webhook Laravel Package

Getting Started

Install the package with Composer and set the default webhook URL in your .env:

composer require discord-webhook/discord-webhook

DWH_DEFAULT_URL=https://discord.com/api/webhooks/...

Clear config cache after changing environment values:

php artisan config:clear

Look first at DiscordWebhook\SimpleWebhook. Its sendMessage() method is the quickest way to get a message into Discord:

use DiscordWebhook\SimpleWebhook;

SimpleWebhook::sendMessage('Deployment finished successfully.');

The first practical use case is operational notifications: deploy completion, queue failures, scheduled task results, or a plain-text alert from a Laravel listener or job. If you need rich embeds, files, or advanced payloads, use the package’s full webhook API rather than SimpleWebhook.

Implementation Patterns

Default-channel notifications. Configure DWH_DEFAULT_URL once and call SimpleWebhook::sendMessage() from anywhere. This keeps most alerts pointed at a single team channel without repeating URLs.

SimpleWebhook::sendMessage('Nightly backup completed.');

Per-message channel overrides. Pass the URL directly when a notification belongs somewhere else:

SimpleWebhook::sendMessage('Billing webhook failed.', config('services.discord.billing_webhook'));

Service wrapper. Avoid scattering the static call through the codebase. Wrap it in a small service or action so sending can be swapped, mocked, or extended later:

namespace App\Services;

use DiscordWebhook\SimpleWebhook;

class DiscordNotifier
{
    public function send(string $message, ?string $url = null): void
    {
        $url
            ? SimpleWebhook::sendMessage($message, $url)
            : SimpleWebhook::sendMessage($message);
    }
}

Queued jobs and listeners. Discord calls are outbound HTTP requests. Send from queued listeners or jobs so a slow or failing Discord endpoint does not block the request lifecycle:

class SendDeploymentNotification implements ShouldQueue
{
    public function handle(DiscordNotifier $notifier): void
    {
        $notifier->send('Deployment completed: '.config('app.env'));
    }
}

Exception reporting. Hook into Laravel’s exception handler or use a listener on MessageLogged for high-severity events. Keep messages short and include enough context to identify the environment and failing component.

Testing. Use Laravel’s HTTP fake in tests rather than sending real Discord traffic:

Http::fake();

SimpleWebhook::sendMessage('Test message');

Http::assertSent(fn ($request) => str_contains($request->url(), 'discord.com'));

Gotchas and Tips

• DWH_DEFAULT_URL is read through Laravel config/environment caching. If messages go to the wrong channel after a deploy, run php artisan config:cache as part of deployment or clear cached config. Changing .env without clearing config can leave the old URL in place.
• Missing default URL. If DWH_DEFAULT_URL is unset and no URL is passed explicitly, SimpleWebhook::sendMessage() cannot know where to send. Validate configuration at boot or in your notifier service and fail with a clear application-level error.
• Treat webhook URLs as secrets. They allow anyone holding them to post into the channel. Keep them in .env, never commit them, and rotate them in Discord if exposed.
• Discord rate limits. Discord returns 429 responses with retry information. If you send bursts of alerts, queue them and use Laravel’s job retry/backoff rather than retrying immediately in a loop.
• Message length limits. Discord caps message content at roughly 2,000 characters. Truncate exception traces and long output before sending.
• SimpleWebhook is for plain text. Use the package’s full webhook classes when you need embeds, components, usernames, avatars, or file uploads. Do not try to force rich payloads through the simple API.
• Network failures should not mask the original failure. When notifying about an exception, catch webhook errors and log them separately. A failed Discord call must not prevent the original exception from being reported.
• Environment labelling. Include app.env in messages where useful; otherwise staging and production alerts can look identical in the same channel.
• Extension point. If you need formatting, retries, or multiple destinations, centralize sending in a service class and keep SimpleWebhook::sendMessage() as the low-level transport call rather than calling it directly throughout the application.