Notifications

​

Supported Notification Services

• Slack: Send messages to Slack channels
• Discord: Post notifications to Discord channels via webhooks
• Telegram: Send messages via Telegram bot
• Email (SMTP): Send emails using custom SMTP server
• Resend: Send emails using Resend API
• Gotify: Push notifications to self-hosted Gotify server
• Ntfy: Publish notifications to ntfy.sh or self-hosted instance
• Lark: Send messages to Lark (Feishu) chat groups
• Microsoft Teams: Post adaptive cards to Teams channels
• Pushover: Send push notifications to mobile devices
• Custom Webhook: POST notifications to custom HTTP endpoints

​

Notification Setup

​

Accessing Notifications

1. Navigate to Settings > Notifications
2. Click Add Notification
3. Select your notification provider
4. Configure provider-specific settings
5. Test the connection
6. Save the notification

​

Slack Configuration

​

Setup Steps

1. Create a Slack App in your workspace
2. Enable Incoming Webhooks
3. Copy the webhook URL
4. Configure in Dokploy

​

Configuration Options

{
  "name": "Production Alerts",
  "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX",
  "channel": "#deployments"
}

​

Example Notification

⚠️ Server Alert
CPU usage (85.50%) exceeded threshold (80.00%)
Server: Dokploy
Timestamp: 2024-01-19 10:30:45 UTC

​

Testing Connection

await api.notification.testSlackConnection.mutate({
  webhookUrl: "https://hooks.slack.com/services/...",
  channel: "#test"
});
// Sends: "Hi, From Dokploy 👋"

​

Discord Configuration

​

Setup Steps

1. Open Discord channel settings
2. Navigate to Integrations > Webhooks
3. Create new webhook
4. Copy webhook URL
5. Configure in Dokploy

​

Configuration Options

{
  "name": "Discord Alerts",
  "webhookUrl": "https://discord.com/api/webhooks/1234567890/ABCDEFGHIJK",
  "decoration": true
}

​

Example Notification

🤚 Test Notification
Hi, From Dokploy 👋

⚠️ CPU Alert
CPU usage (85.50%) exceeded threshold (80.00%)
Server: Dokploy
Timestamp: 2024-01-19T10:30:45.000Z

​

Testing Connection

await api.notification.testDiscordConnection.mutate({
  webhookUrl: "https://discord.com/api/webhooks/...",
  decoration: true
});

​

Telegram Configuration

​

Setup Steps

1. Create a bot using @BotFather
2. Get bot token from BotFather
3. Get your chat ID (use @userinfobot)
4. Configure in Dokploy

​

Configuration Options

{
  "name": "Telegram Notifications",
  "botToken": "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
  "chatId": "-1001234567890"
}

​

Example Notification

Hi, From Dokploy 👋

⚠️ Memory Alert
Memory usage (87.50%) exceeded threshold (85.00%)
Server: Dokploy
Time: 2024-01-19 10:30:45 UTC

​

Testing Connection

await api.notification.testTelegramConnection.mutate({
  botToken: "1234567890:ABC...",
  chatId: "-1001234567890"
});

​

Email (SMTP) Configuration

​

Configuration Options

{
  "name": "Email Alerts",
  "smtpServer": "smtp.gmail.com",
  "smtpPort": 587,
  "username": "[email protected]",
  "password": "your-app-password",
  "fromAddress": "[email protected]",
  "toAddresses": ["[email protected]", "[email protected]"]
}

​

Common SMTP Servers

​

Testing Connection

await api.notification.testEmailConnection.mutate({
  smtpServer: "smtp.gmail.com",
  smtpPort: 587,
  username: "[email protected]",
  password: "app-password",
  fromAddress: "[email protected]",
  toAddresses: ["[email protected]"]
});
// Sends test email: "Hi, From Dokploy 👋"

​

Resend Configuration

​

Setup Steps

1. Sign up at resend.com
2. Create an API key
3. Verify your domain
4. Configure in Dokploy

​

Configuration Options

{
  "name": "Resend Notifications",
  "apiKey": "re_123456789",
  "fromAddress": "[email protected]",
  "toAddresses": ["[email protected]"]
}

​

Testing Connection

await api.notification.testResendConnection.mutate({
  apiKey: "re_123456789",
  fromAddress: "[email protected]",
  toAddresses: ["[email protected]"]
});

​

Gotify Configuration

​

Configuration Options

{
  "name": "Gotify Alerts",
  "serverUrl": "https://gotify.yourdomain.com",
  "token": "AzHgQwerTyuiop"
}

​

Ntfy Configuration

​

Configuration Options

{
  "name": "Ntfy Alerts",
  "topic": "dokploy-alerts",
  "serverUrl": "https://ntfy.sh",
  "username": "optional-username",
  "password": "optional-password"
}

​

Testing Connection

await api.notification.testNtfyConnection.mutate({
  topic: "dokploy-alerts",
  serverUrl: "https://ntfy.sh"
});

​

Lark (Feishu) Configuration

​

Configuration Options

{
  "name": "Lark Notifications",
  "webhookUrl": "https://open.feishu.cn/open-apis/bot/v2/hook/..."
}

​

Microsoft Teams Configuration

​

Configuration Options

{
  "name": "Teams Alerts",
  "webhookUrl": "https://outlook.office.com/webhook/..."
}

​

Pushover Configuration

​

Configuration Options

{
  "name": "Pushover Alerts",
  "apiToken": "your-app-token",
  "userKey": "your-user-key"
}

​

Custom Webhook Configuration

​

Configuration Options

{
  "name": "Custom Webhook",
  "webhookUrl": "https://api.yourdomain.com/webhooks/dokploy",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-token",
    "Content-Type": "application/json"
  }
}

​

Webhook Payload

{
  "title": "CPU Alert",
  "message": "CPU usage (85.50%) exceeded threshold (80.00%)",
  "timestamp": "2024-01-19T10:30:45.000Z"
}

​

Notification Events

​

Monitoring Alerts

• CPU Threshold Exceeded: When CPU usage goes above the configured limit
• Memory Threshold Exceeded: When memory usage goes above the configured limit

{
  ServerType: "Dokploy",
  Type: "CPU",
  Value: 85.5,
  Threshold: 80,
  Message: "CPU usage (85.50%) exceeded threshold (80.00%)",
  Timestamp: "2024-01-19T10:30:45.000Z",
  Token: "your-secure-token"
}

​

Setting Up Threshold Notifications

1. Configure monitoring thresholds in Settings > Monitoring:

{
  "thresholds": {
    "cpu": 80,      // Alert when CPU > 80%
    "memory": 85    // Alert when Memory > 85%
  }
}

2. Set callback URL to Dokploy’s notification endpoint:

http://localhost:3000/api/trpc/notification.receiveNotification

3. Configure notification providers to receive the alerts

​

Managing Notifications

​

List All Notifications

const notifications = await api.notification.all.query();

​

Update Notification

await api.notification.updateSlack.mutate({
  notificationId: "notif-id",
  webhookUrl: "https://hooks.slack.com/services/...",
  channel: "#new-channel"
});

​

Delete Notification

await api.notification.remove.mutate({
  notificationId: "notif-id"
});

​

Best Practices

1. Test Connections: Always test notifications after configuration to ensure they work
2. Use Descriptive Names: Give notifications clear names to identify their purpose
3. Separate Channels: Use different channels for different alert types (e.g., #deployments, #critical-alerts)
4. Set Appropriate Thresholds: Configure thresholds that match your normal operating ranges
5. Avoid Alert Fatigue: Don’t set thresholds too low or you’ll receive too many notifications
6. Secure Credentials: Store notification credentials securely and rotate them regularly
7. Monitor Notification Delivery: Verify that critical alerts are being received
8. Use Multiple Channels: Configure redundant notification channels for critical alerts

​

Troubleshooting

​

Notifications Not Sending

1. Verify configuration: Check webhook URLs, tokens, and credentials
2. Test connection: Use the test button to verify the provider is reachable
3. Check permissions: Ensure bot/app has permission to post in target channel
4. Verify thresholds: Make sure monitoring thresholds are properly configured
5. Check callback URL: Ensure the urlCallback points to the correct endpoint

​

Slack Issues

• Invalid webhook: Generate a new webhook URL in Slack settings
• Channel not found: Verify the channel name includes the # symbol
• Permission denied: Add the Slack app to the target channel

​

Discord Issues

• Webhook expired: Create a new webhook in Discord channel settings
• Rate limited: Discord limits webhook calls; reduce notification frequency

​

Telegram Issues

• Invalid bot token: Verify token from @BotFather
• Wrong chat ID: Use @userinfobot to get correct chat ID
• Bot not in group: Add the bot to the group/channel first

​

Email Issues

• Authentication failed: Check username/password or use app-specific password
• Connection timeout: Verify SMTP server and port are correct
• TLS errors: Try different ports (587 for STARTTLS, 465 for SSL)

​

Example Notification Flow

1. Monitoring service detects CPU usage at 85%
2. Threshold check compares against configured limit (80%)
3. Notification triggered with alert details
4. Callback URL receives POST request with alert payload
5. Dokploy routes notification to configured providers
6. Messages sent to Slack, Discord, Telegram, etc.
7. Team receives alerts and can respond to the issue

​

Next Steps

• Configure Real-Time Metrics to enable threshold alerts
• View Monitoring Overview for complete observability setup
• Check Application Logs for detailed troubleshooting