Skip to main content
Integrate Dokploy with Discord to receive real-time notifications about deployments, build failures, backups, and system events directly in your Discord server channels.

​
Prerequisites

  • A Discord server where you have Manage Webhooks permission
  • Admin access to your Dokploy organization

​
Creating a Discord Webhook

1

Open Server Settings

Right-click on your Discord server icon and select Server Settings
2

Navigate to Integrations

In the left sidebar, click Integrations
3

Create Webhook

  • Click Webhooks or View Webhooks
  • Click New Webhook or Create Webhook
4

Configure Webhook

  • Name your webhook (e.g., “Dokploy Notifications”)
  • Select the channel where notifications should appear
  • (Optional) Upload a custom avatar for the webhook
5

Copy Webhook URL

Click Copy Webhook URL. It will look like:
https://discord.com/api/webhooks/1234567890/ABCDEFGHIJKLMNOP
6

Save Webhook

Click Save Changes in Discord to finalize the webhook

​
Configuring Discord in Dokploy

1

Navigate to Notifications

In Dokploy, go to Settings > Notifications
2

Add Discord Notification

Click Add Notification and select Discord
3

Enter Configuration

Provide the following details:
  • Name: A descriptive name for this notification (e.g., “Production Alerts”)
  • Webhook URL: Paste the webhook URL from Discord
  • Enable Decoration: Toggle to add markdown quote decorations (>) to messages
4

Select Events

Choose which events should trigger Discord notifications:
  • Application Deploy
  • Application Build Error
  • Database Backup
  • Volume Backup
  • Dokploy Restart
  • Docker Cleanup
  • Server Threshold Exceeded
5

Test Connection

Click Test Connection to send a test embed to your Discord channel
6

Save Configuration

Click Save to activate the notification channel

​
Configuration Schema

The Discord notification configuration uses the following structure: 
{
  name: string,              // Display name for the notification
  webhookUrl: string,        // Discord webhook URL (required)
  decoration: boolean,       // Add quote decoration to messages
  appDeploy: boolean,        // Enable for deployment notifications
  appBuildError: boolean,    // Enable for build failure alerts
  databaseBackup: boolean,   // Enable for database backup notifications
  volumeBackup: boolean,     // Enable for volume backup notifications
  dokployRestart: boolean,   // Enable for Dokploy restart alerts
  dockerCleanup: boolean,    // Enable for cleanup notifications
  serverThreshold: boolean   // Enable for resource threshold warnings
}

​
Notification Format

Discord notifications from Dokploy use rich embeds with the following structure:

​
Test Notification

{
  title: "> `🤚` - Test Notification",  // With decoration enabled
  description: "> Hi, From Dokploy 👋",
  color: 0xf3f7f4  // Light gray color
}

​
Event Notifications

Production notifications include:
  • Title: Event type with emoji indicator
  • Description: Event details and context
  • Color: Status-based color coding (green for success, red for errors)
  • Timestamp: Automatically added by Discord

​
Message Decoration

The decoration option controls whether messages are formatted with markdown quotes: 
🤚 Test Notification
Hi, From Dokploy 👋
Decorated messages appear with a left border in Discord, making them visually distinct from regular messages. This is useful for quickly identifying automated notifications.

​
Webhook Permissions

The Discord webhook created for Dokploy has the following capabilities:
  • ✅ Send messages to the specified channel
  • ✅ Send rich embeds with formatting
  • ✅ Use custom username and avatar (configured in Discord)
  • ❌ Cannot read messages or channel history
  • ❌ Cannot manage channels or roles
Webhooks have limited permissions by design. They can only post messages to the channel they’re configured for, making them safe for integration purposes.

​
Troubleshooting

​
Test Connection Fails

Invalid webhook URL
  • Verify the webhook URL is correct and complete
  • Ensure the URL starts with https://discord.com/api/webhooks/
  • Check that the webhook hasn’t been deleted in Discord
Webhook deleted or disabled
  • Navigate to Server Settings > Integrations > Webhooks in Discord
  • Verify the webhook still exists and is enabled
  • If deleted, create a new webhook and update Dokploy
Rate limiting
  • Discord has rate limits for webhooks (30 requests per minute)
  • If you receive rate limit errors, notifications will be queued and retried

​
Not Receiving Notifications

Check event configuration
  • Verify the notification is enabled for the events you want to receive
  • Confirm events are being triggered in Dokploy (check logs)
Channel permissions
  • Ensure the channel still exists in your Discord server
  • Verify webhooks are allowed in the channel (some channels may have restrictions)
Server settings
  • Check if your Discord server has disabled webhooks
  • Verify you haven’t reached the webhook limit for your server
If you delete a webhook in Discord, the webhook URL becomes invalid immediately. You must create a new webhook and update the configuration in Dokploy.

​
Best Practices

​
Organize by Environment

Create separate Discord channels for different environments:
  • #production-alerts: Critical production events
  • #staging-deploys: Staging deployments and tests
  • #backups: Database and volume backups
  • #monitoring: System resource monitoring

​
Use Clear Webhook Names

Name your webhooks descriptively in Discord:
  • ✅ “Dokploy Production”
  • ✅ “Dokploy Staging”
  • ❌ “Webhook 1”

​
Enable Decoration for Visibility

Enable the decoration option to make automated notifications stand out from regular chat messages.

​
Role Mentions (Advanced)

While Dokploy doesn’t directly support role mentions, you can configure Discord channel notifications to ping specific roles when webhooks post messages.

​
API Integration

Manage Discord notifications programmatically using the Dokploy API: 
const notification = await api.notification.createDiscord({
  name: "Production Alerts",
  webhookUrl: "https://discord.com/api/webhooks/...",
  decoration: true,
  appDeploy: true,
  appBuildError: true,
  serverThreshold: true,
  databaseBackup: false,
  volumeBackup: false,
  dokployRestart: true,
  dockerCleanup: false
});

​
Webhook Security

​
Protecting Your Webhook URL

  • Keep URLs secret: Webhook URLs grant posting access to your channel
  • Regenerate if exposed: Delete and recreate webhooks if URLs are compromised
  • Limit access: Only share webhook URLs with trusted systems

​
Revoking Access

To revoke a webhook’s access:
1

Open Discord Integrations

Go to Server Settings > Integrations > Webhooks
2

Delete Webhook

Find the webhook and click Delete Webhook
3

Update Dokploy

Remove or update the notification configuration in Dokploy

​
Limits and Quotas

  • Rate Limit: 30 requests per minute per webhook
  • Message Length: 2000 characters per message
  • Embed Limit: 10 embeds per message
  • Webhooks per Channel: 15 webhooks maximum
  • Webhooks per Server: 100 webhooks maximum
Dokploy respects Discord’s rate limits and will automatically queue notifications if the limit is reached.

​
Next Steps

Slack Notifications

Set up Slack webhook integration

Telegram Notifications

Configure Telegram bot alerts

Email Notifications

Set up SMTP email notifications

Notification Overview

Learn about all notification options