Discord Webhooks

Vail includes built-in Discord webhook notifications. When configured, status alerts and incident updates can be published directly to designated Discord channels with formatted embeds and severity indicators.

Configuration

In settings.json, populate the discord configuration block:

settings.json

{
  "discord": {
    "enabled": true,
    "webhookUrl": "https://discord.com/api/webhooks/1234567890/abcdefghijklmnopqrstuvwxyz",
    "username": "Vail Status",
    "avatarUrl": "https://example.com/status-avatar.png"
  }
}

Field	Type	Description
`enabled`	`boolean`	Set to `true` to enable outbound Discord notifications.
`webhookUrl`	`string`	The Discord Incoming Webhook URL created in channel settings.
`username`	`string`	Optional webhook sender username override.
`avatarUrl`	`string`	Optional avatar image URL for the webhook bot.

Notification Colors & Statuses

Vail maps service health states to Discord embed side-strip colors:

Operational: Green (#22c55e / decimal 2278750)
Degraded: Yellow (#eab308 / decimal 15381256)
Outage / Error: Red (#ef4444 / decimal 15680580)
Maintenance / Info: Blue (#3b82f6 / decimal 3899894)

API Notification Route (`/api/notify`)

Vail provides an internal HTTP POST endpoint at /api/notify to trigger Discord notifications programmatically from external scripts, cron jobs, or monitoring systems.

Request Format

Method: POST
Path: /api/notify
Headers: Content-Type: application/json

Body Parameters

Parameter	Type	Required	Description
`title`	`string`	Yes	Embed title summarizing the event.
`message`	`string`	Yes	Detailed description or incident note.
`status`	`string`	Optional	`operational`, `degraded`, `outage`, or `maintenance`.
`type`	`string`	Optional	`info`, `warning`, or `error`.
`url`	`string`	Optional	URL link attached to the embed title.

Example cURL

curl -X POST http://localhost:3000/api/notify \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Scheduled Maintenance Completed",
    "message": "All core database migrations finished successfully.",
    "status": "operational",
    "url": "https://status.example.com"
  }'

Response

On success, the endpoint returns:

{
  "success": true
}