Notifications - Dokploy

Overview

Dokploy can send notifications to multiple channels when important events occur. Configure notifications once and receive alerts for deployments, errors, backups, and system events.

Supported Channels

Dokploy integrates with 10+ notification services:

Slack - Team messaging platform
Discord - Community and team chat
Telegram - Instant messaging
Email - SMTP email notifications
Resend - Modern email API
Gotify - Self-hosted push notifications
Ntfy - Simple HTTP-based notifications
Pushover - Push notifications for iOS and Android
Lark - Enterprise collaboration platform
Microsoft Teams - Team collaboration
Custom - Webhook to any HTTP endpoint

Event Types

Configure which events trigger notifications:

appDeploy

boolean

default:"false"

Notify when applications are successfully deployed

appBuildError

boolean

default:"false"

Notify when application builds or deployments fail

databaseBackup

boolean

default:"false"

Notify when database backups complete or fail

volumeBackup

boolean

default:"false"

Notify when volume backups complete or fail

dokployRestart

boolean

default:"false"

Notify when Dokploy server restarts

dockerCleanup

boolean

default:"false"

Notify when Docker cleanup tasks run

serverThreshold

boolean

default:"false"

Notify when server CPU or memory exceeds configured thresholds

Slack

Send notifications to Slack channels using webhooks.

Configuration

name

string

required

Display name for this notification channel

Production Deployments

webhookUrl

string

required

Slack webhook URL

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX

channel

string

Slack channel name (optional, defaults to webhook’s configured channel)

#deployments

Creating a Slack Webhook

Go to Slack API: Incoming Webhooks
Create a new app or select existing one
Enable Incoming Webhooks
Add webhook to workspace
Select channel and copy webhook URL

Example

curl -X POST https://your-domain.com/api/trpc/notification.createSlack \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Alerts",
    "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXX",
    "channel": "#deployments",
    "appDeploy": true,
    "appBuildError": true,
    "databaseBackup": true
  }'

Discord

Send notifications to Discord channels using webhooks.

Configuration

name

string

required

Display name for this notification channel

webhookUrl

string

required

Discord webhook URL

https://discord.com/api/webhooks/123456789/abcdefghijk

decoration

boolean

Enable rich embeds with colors and formatting

Creating a Discord Webhook

Open Discord channel settings
Go to Integrations > Webhooks
Click “New Webhook”
Configure name and channel
Copy webhook URL

Example

curl -X POST https://your-domain.com/api/trpc/notification.createDiscord \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Discord Notifications",
    "webhookUrl": "https://discord.com/api/webhooks/123456789/abcdefghijk",
    "decoration": true,
    "appDeploy": true,
    "appBuildError": true
  }'

Send notifications to Telegram chats using a bot.

Configuration

name

string

required

Display name for this notification channel

botToken

string

required

Telegram bot token from BotFather

123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

chatId

string

required

Telegram chat ID to send messages to

# User chat
123456789

# Group chat (negative number)
-1001234567890

messageThreadId

string

Thread ID for topics in groups (optional)

Creating a Telegram Bot

Message @BotFather on Telegram
Send /newbot command
Follow prompts to create bot
Copy the bot token
Add bot to your chat/channel
Get chat ID using @userinfobot

Example

curl -X POST https://your-domain.com/api/trpc/notification.createTelegram \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Telegram Alerts",
    "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "chatId": "123456789",
    "appDeploy": true,
    "appBuildError": true,
    "serverThreshold": true
  }'

Email (SMTP)

Send notifications via SMTP email.

Configuration

name

string

required

Display name for this notification channel

smtpServer

string

required

SMTP server hostname

smtp.gmail.com

smtpPort

number

required

SMTP server port

587 - TLS (recommended)
465 - SSL
25 - Unencrypted (not recommended)

username

string

required

SMTP authentication username

password

string

required

SMTP authentication password

fromAddress

string

required

Email address to send from

[email protected]

toAddresses

array

required

List of recipient email addresses

["[email protected]", "[email protected]"]

Example

curl -X POST https://your-domain.com/api/trpc/notification.createEmail \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email Notifications",
    "smtpServer": "smtp.gmail.com",
    "smtpPort": 587,
    "username": "[email protected]",
    "password": "app-specific-password",
    "fromAddress": "[email protected]",
    "toAddresses": ["[email protected]"],
    "appBuildError": true,
    "databaseBackup": true
  }'

Resend

Send notifications using the Resend email API.

Configuration

name

string

required

Display name for this notification channel

apiKey

string

required

Resend API key

re_123456789_abcdefghijklmnop

fromAddress

string

required

Email address to send from (must be verified in Resend)

[email protected]

toAddresses

array

required

List of recipient email addresses

Example

curl -X POST https://your-domain.com/api/trpc/notification.createResend \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Resend Notifications",
    "apiKey": "re_123456789_abcdefghijklmnop",
    "fromAddress": "[email protected]",
    "toAddresses": ["[email protected]"],
    "appDeploy": true,
    "appBuildError": true
  }'

Gotify

Send push notifications to self-hosted Gotify server.

Configuration

name

string

required

Display name for this notification channel

serverUrl

string

required

Gotify server URL

https://gotify.example.com

appToken

string

required

Gotify application token

priority

number

default:"5"

Message priority (0-10)

0 - Very low
5 - Normal (default)
10 - Emergency

decoration

boolean

Enable markdown formatting in messages

Example

curl -X POST https://your-domain.com/api/trpc/notification.createGotify \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gotify Alerts",
    "serverUrl": "https://gotify.example.com",
    "appToken": "AaBbCcDd123456",
    "priority": 8,
    "decoration": true,
    "appBuildError": true
  }'

Ntfy

Send notifications via ntfy.sh or self-hosted ntfy server.

Configuration

name

string

required

Display name for this notification channel

serverUrl

string

required

Ntfy server URL

# Public ntfy.sh
https://ntfy.sh

# Self-hosted
https://ntfy.example.com

topic

string

required

Ntfy topic name

dokploy-alerts

accessToken

string

Access token for protected topics (optional)

priority

number

default:"3"

Message priority (1-5)

1 - Min
3 - Default
5 - Max/Urgent

Example

curl -X POST https://your-domain.com/api/trpc/notification.createNtfy \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ntfy Notifications",
    "serverUrl": "https://ntfy.sh",
    "topic": "dokploy-prod",
    "priority": 4,
    "appDeploy": true,
    "appBuildError": true
  }'

Pushover

Send push notifications to iOS and Android via Pushover.

Configuration

name

string

required

Display name for this notification channel

userKey

string

required

Pushover user key

uQiRzpo4DXghDmr9QzzfQu27cmVRsG

apiToken

string

required

Pushover application API token

azGDORePK8gMaC0QOYAMyEEuzJnyUi

priority

number

default:"0"

Message priority

-2 - Lowest (no notification)
-1 - Low (no sound/vibration)
0 - Normal
1 - High
2 - Emergency (requires acknowledgment)

retry

number

Retry interval in seconds (required for emergency priority)Minimum: 30 seconds

expire

number

Expiration time in seconds (required for emergency priority)Maximum: 10800 seconds (3 hours)

Example

curl -X POST https://your-domain.com/api/trpc/notification.createPushover \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pushover Alerts",
    "userKey": "uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
    "apiToken": "azGDORePK8gMaC0QOYAMyEEuzJnyUi",
    "priority": 1,
    "appBuildError": true,
    "serverThreshold": true
  }'

Lark

Send notifications to Lark (Feishu) using webhooks.

Configuration

name

string

required

Display name for this notification channel

webhookUrl

string

required

Lark webhook URL

https://open.larksuite.com/open-apis/bot/v2/hook/xxxxxxxx

Example

curl -X POST https://your-domain.com/api/trpc/notification.createLark \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lark Notifications",
    "webhookUrl": "https://open.larksuite.com/open-apis/bot/v2/hook/xxx",
    "appDeploy": true,
    "appBuildError": true
  }'

Microsoft Teams

Send notifications to Microsoft Teams channels.

Configuration

name

string

required

Display name for this notification channel

webhookUrl

string

required

Teams webhook URL

https://outlook.office.com/webhook/xxx/IncomingWebhook/yyy

Creating a Teams Webhook

Open Teams channel
Click ”…” > Connectors
Search for “Incoming Webhook”
Configure and create
Copy webhook URL

Example

curl -X POST https://your-domain.com/api/trpc/notification.createTeams \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Teams Notifications",
    "webhookUrl": "https://outlook.office.com/webhook/xxx/IncomingWebhook/yyy",
    "appDeploy": true,
    "appBuildError": true,
    "databaseBackup": true
  }'

Custom Webhook

Send notifications to any HTTP endpoint.

Configuration

name

string

required

Display name for this notification channel

endpoint

string

required

HTTP endpoint URL

https://api.example.com/notifications

headers

object

Custom HTTP headers

{
  "Authorization": "Bearer token123",
  "Content-Type": "application/json"
}

Payload Format

Dokploy sends POST requests with this JSON payload:

{
  "event": "appDeploy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "applicationName": "my-app",
    "status": "success",
    "message": "Application deployed successfully"
  }
}

Example

curl -X POST https://your-domain.com/api/trpc/notification.createCustom \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Webhook",
    "endpoint": "https://api.example.com/notifications",
    "headers": {
      "Authorization": "Bearer token123"
    },
    "appDeploy": true,
    "appBuildError": true
  }'

Managing Notifications

List All Notifications

curl https://your-domain.com/api/trpc/notification.getAll \
  -H "x-api-key: your-api-key"

Update Notification

curl -X POST https://your-domain.com/api/trpc/notification.updateSlack \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "notificationId": "notif-123",
    "name": "Updated Name",
    "appDeploy": false,
    "appBuildError": true
  }'

Delete Notification

curl -X POST https://your-domain.com/api/trpc/notification.delete \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"notificationId": "notif-123"}'

Test Notification

curl -X POST https://your-domain.com/api/trpc/notification.testSlack \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://hooks.slack.com/services/...",
    "channel": "#test"
  }'

Authorization

Notifications are scoped to organizations
Users can only manage notifications in their active organization
Admin role required for creating/updating notifications

Best Practices

Start Small: Begin with build errors only, then expand
Channel Strategy: Use different channels for different severity levels
Test First: Always test notifications before deploying
Rate Limiting: Be aware of rate limits on notification services
Redundancy: Configure multiple channels for critical alerts

Troubleshooting

Notifications Not Sending

Test the connection using the test endpoint
Verify credentials are correct
Check event toggles are enabled
Review Dokploy server logs

Slack Webhook Invalid

Ensure webhook URL is complete
Verify webhook wasn’t deleted in Slack
Check channel still exists
Confirm bot has channel access

Email Not Delivering

Verify SMTP credentials
Check firewall allows SMTP port
Confirm from address is authorized
Review spam folders

Overview

Getting Started

Core Concepts

Deployments

Databases

Monitoring & Observability

Advanced Features

Configuration

CLI & Automation

Community & Support

​Overview

​Supported Channels

​Event Types

​Slack

​Configuration

​Creating a Slack Webhook

​Example

​Discord

​Configuration

​Creating a Discord Webhook

​Example

​Telegram

​Configuration

​Creating a Telegram Bot

​Example

​Email (SMTP)

​Configuration

​Example

​Resend

​Configuration

​Example

​Gotify

​Configuration

​Example

​Ntfy

​Configuration

​Example

​Pushover

​Configuration

​Example

​Lark

​Configuration

​Example

​Microsoft Teams

​Configuration

​Creating a Teams Webhook

​Example

​Custom Webhook

​Configuration

​Payload Format

​Example

​Managing Notifications

​List All Notifications

​Update Notification

​Delete Notification

​Test Notification

​Authorization

​Best Practices

​Troubleshooting

Build docs developers (and LLMs) love

Overview

Supported Channels

Event Types

Slack

Configuration

Creating a Slack Webhook

Example

Discord

Configuration

Creating a Discord Webhook

Example

Telegram

Configuration

Creating a Telegram Bot

Example

Email (SMTP)

Configuration

Example

Resend

Configuration

Example

Gotify

Configuration

Example

Ntfy

Configuration

Example

Pushover

Configuration

Example

Lark

Configuration

Example

Microsoft Teams

Configuration

Creating a Teams Webhook

Example

Custom Webhook

Configuration

Payload Format

Example

Managing Notifications

List All Notifications

Update Notification

Delete Notification

Test Notification

Authorization

Best Practices

Troubleshooting