Skip to content

Discord Webhook Setup Guide

Guide to the 4 application-alert channels and their webhooks for the Freeze Design alerting system. These are the channels the running application posts to (DISCORD_WEBHOOK_{ERRORS,PAYMENTS,BACKUPS,ADMIN} in the env file on the VPS, with legacy-name fallbacks). What arrives where, and how to respond, is in the Alerting runbook.

Moving to ntfy

Every application alert now also goes to the self-hosted ntfy server; see ntfy notifications. Discord stays until the transition is over.

This page covers application alerts only

The CI/CD channels are configured as GitHub Actions secrets, not VPS env vars; see Other Discord webhooks below for the full secret list. Sentry sends e-mail and does not post to Discord (see Monitoring). A #monitoring channel for an external uptime monitor does not exist yet (see Monitoring).

Overview

The application alerting uses 4 Discord channels, each with a specific purpose:

Channel Purpose Notification Source Env Var (preferred)
#errors Disk-space alerts; celery-beat restarted by cron Django DiscordService; scripts/restart-unhealthy.sh reads the same env var DISCORD_WEBHOOK_ERRORS
#payments Payment anomalies (every 15 min), daily payment summary (07:00 Dutch time), repaired paid orders Django DiscordService DISCORD_WEBHOOK_PAYMENTS
#backups Backup success/failure, cleanup, verification, restore test, daily summary (06:00 Dutch time) Django DiscordService DISCORD_WEBHOOK_BACKUPS
#production-admin-actions Admin audit trail (delete, bulk_delete), paid orders, stock problems, failed refunds, Informer booking failures (apps/informer/notify.py, since v1.53) Django DiscordService DISCORD_WEBHOOK_ADMIN

All four go through one mechanism: a custom Discord webhook per channel, called by the shared DiscordService (backend/apps/core/services/discord_service.py). It never raises (a failed post is logged as a warning, not retried) and sends at most 5 messages per channel per minute. The cron script restart-unhealthy.sh posts with curl to the DISCORD_WEBHOOK_ERRORS URL from the env file next to the compose file.

Production has all four set since 2026-09-28.

Channel Setup

Organizing alert channels under a category keeps your Discord server tidy.

  1. Right-click your server name at the top of the channel list
  2. Select Create Category
  3. Name it FREEZE DESIGN ALERTS (or similar)
  4. Click Create Category

Step 2: Create the 4 Channels

For each channel in the table below:

  1. Click the + next to the category name (or next to "Text Channels")
  2. Select Text Channel
  3. Enter the channel name
  4. Click Create Channel
Channel Name Description to Set
errors Disk-space alerts and celery-beat restarts
payments Payment anomalies, daily payment summary, repaired orders
backups Backup results, daily summary, restore test
production-admin-actions Admin deletes, paid orders, stock problems, failed refunds, Informer failures

To prevent accidental messages in alert channels:

  1. Click the gear icon next to the channel name (Edit Channel)
  2. Go to Permissions
  3. Under @everyone, deny Send Messages
  4. Webhooks bypass role permissions, so nothing else is needed

Webhook Creation

One webhook per channel, four in total. For each channel:

  1. Right-click the channel
  2. Select Edit Channel
  3. Go to Integrations in the left menu
  4. Click Webhooks
  5. Click New Webhook
  6. Set the name (Freeze Design Errors, Freeze Design Payments, Freeze Design Backups, Freeze Design Admin)
  7. Optionally upload an avatar image
  8. Click Copy Webhook URL
  9. Save the URL in the password manager -- you will need it for the environment variable

Environment Variables

Setting them on the VPS

Add these to the environment file of the target VPS (backend/.env.staging or backend/.env.production). Containers only read the file when they are created, so recreate them afterwards (docker compose -f docker-compose.prod.yml up -d backend celery celery-beat); a plain restart is not enough. The cron script reads the file on every run.

# Discord Webhook URLs (custom notifications from Django and restart-unhealthy.sh)
DISCORD_WEBHOOK_ERRORS=https://discord.com/api/webhooks/YOUR_ERRORS_WEBHOOK_ID/YOUR_TOKEN
DISCORD_WEBHOOK_PAYMENTS=https://discord.com/api/webhooks/YOUR_PAYMENTS_WEBHOOK_ID/YOUR_TOKEN
DISCORD_WEBHOOK_BACKUPS=https://discord.com/api/webhooks/YOUR_BACKUPS_WEBHOOK_ID/YOUR_TOKEN
DISCORD_WEBHOOK_ADMIN=https://discord.com/api/webhooks/YOUR_ADMIN_WEBHOOK_ID/YOUR_TOKEN

Legacy Environment Variable Migration

The codebase previously used different env var names. DiscordService reads the new DISCORD_WEBHOOK_* names first and falls back to the legacy names:

Legacy Variable (fallback) New Variable (preferred) Channel
BACKUP_DISCORD_WEBHOOK DISCORD_WEBHOOK_BACKUPS backups
ADMIN_DISCORD_WEBHOOK DISCORD_WEBHOOK_ADMIN admin
DISK_ALERT_DISCORD_WEBHOOK DISCORD_WEBHOOK_ERRORS errors (disk space alerts)

Setting only the new variables is sufficient. manage.py backup_health still reports the legacy BACKUP_DISCORD_WEBHOOK setting as "NOT SET" when only the new name is used; that line is cosmetic. restart-unhealthy.sh knows only the new DISCORD_WEBHOOK_ERRORS.

Other Discord webhooks (CI/CD, not part of this alerting setup)

The GitHub Actions workflows use separate webhook secrets (configured in the repo settings, not in VPS env files):

Secret Used By
DISCORD_WEBHOOK_URL Generic fallback; staging deploy notifications (deploy-staging.yml), the k6 gate (staging-perf-gate.yml) and the E2E smoke after a staging deploy (e2e-staging.yml, only when red)
DISCORD_WEBHOOK_CICD CI completion (ci.yml notify jobs), SSL renewal and expiry check (ssl-renewal.yml)
DISCORD_WEBHOOK_STAGING_BACKUPS Weekly CI backup test (backup-test.yml)
DISCORD_WEBHOOK_PRODUCTION Production deploys (deploy-production.yml; falls back to DISCORD_WEBHOOK_CICD, then DISCORD_WEBHOOK_URL)
DISCORD_WEBHOOK_DAGPLANNING The daily planning: dagbouw-bewaker.yml, dagplanning-waakhond.yml and websitecheck-discord.yml (see Dagplanning)

The workflows that call scripts/notify-discord.sh also pass NTFY_URL and the secret NTFY_TOKEN_CI, so the same message goes to ntfy topic freeze-deploy (ntfy notifications). The daily-planning messages stay on Discord only.

The feedback repo (Voorman/freezedesign-feedback) additionally uses DISCORD_WEBHOOK_EEFJE_FEEDBACK for the #eefje-feedback channel — see the Eefje Feedback Intake runbook.

Testing Webhooks

Test with curl

After creating webhooks, verify they work before deploying:

curl -H "Content-Type: application/json" \
  -X POST \
  -d '{"embeds": [{"title": "Test: Backup Webhook", "description": "If you see this, the #backups webhook is working.", "color": 3066993}]}' \
  "https://discord.com/api/webhooks/YOUR_BACKUPS_WEBHOOK_ID/YOUR_TOKEN"

You should see a green-colored embed message appear in #backups (HTTP 204 on the command line). Repeat for the other three URLs.

Test from Django

On the VPS, verify Django can send to every configured channel:

docker compose -f docker-compose.prod.yml exec backend python manage.py shell -c "
from apps.core.services.discord_service import DiscordService
d = DiscordService()
for ch in ('errors', 'payments', 'backups', 'admin'):
    print(ch, d.is_configured(ch), d.send_embed(channel=ch, title='Test from Django', description='webhook ok', color=DiscordService.COLOR_INFO))
"

Each channel prints True True and shows a blue embed.

Verification Checklist

Check Command / Action Expected Result
Each webhook works curl test (above) Embed appears in the channel
Django can reach the webhooks Django shell test (above) True True per channel
Env vars are set docker compose -f docker-compose.prod.yml exec backend env \| grep DISCORD All four URLs shown
Cron script finds the webhook scripts/restart-unhealthy.sh docker-compose.prod.yml celery-beat while beat is healthy exits silently (it only posts when the service is unhealthy)

Security Notes

  • Never commit webhook URLs to version control. They are secrets that allow anyone to post to your channels.
  • Store webhook URLs only in the VPS env file (backend/.env.staging / backend/.env.production, with chmod 600 permissions) or in GitHub Actions secrets.
  • If a webhook URL is compromised, delete the webhook in Discord and create a new one.
  • Regenerating a webhook URL invalidates the old one immediately.