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¶
Step 1: Create a Category (Optional but Recommended)¶
Organizing alert channels under a category keeps your Discord server tidy.
- Right-click your server name at the top of the channel list
- Select Create Category
- Name it
FREEZE DESIGN ALERTS(or similar) - Click Create Category
Step 2: Create the 4 Channels¶
For each channel in the table below:
- Click the + next to the category name (or next to "Text Channels")
- Select Text Channel
- Enter the channel name
- 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 |
Step 3: Set Channel Permissions (Recommended)¶
To prevent accidental messages in alert channels:
- Click the gear icon next to the channel name (Edit Channel)
- Go to Permissions
- Under
@everyone, deny Send Messages - Webhooks bypass role permissions, so nothing else is needed
Webhook Creation¶
One webhook per channel, four in total. For each channel:
- Right-click the channel
- Select Edit Channel
- Go to Integrations in the left menu
- Click Webhooks
- Click New Webhook
- Set the name (
Freeze Design Errors,Freeze Design Payments,Freeze Design Backups,Freeze Design Admin) - Optionally upload an avatar image
- Click Copy Webhook URL
- 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, withchmod 600permissions) 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.