§12 Discord Staff Alerts
Discord Staff Alerts#
In-game staff alerts (/ff alerts) need no setup — alerts.yml's ingame.* block is enabled by
default. This page covers the optional Discord side; see
Configuration § alerts.yml for the full key reference for
both.
Create a Discord webhook#
In Discord, go to the target channel's Settings → Integrations → Webhooks → New Webhook, name it (e.g. "FlagForge"), and copy its URL. Use a private staff-only channel — the webhook URL is a secret equivalent to a password for posting there.
Set the webhook URL#
Set it as an environment variable before starting the server:
export FLAGFORGE_DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/…"
No environment variables on your host?#
Paste the webhook URL directly into alerts.yml's webhook-url value instead of the
${FLAGFORGE_DISCORD_WEBHOOK_URL} placeholder — it works the same either way. FlagForge logs a
one-time startup reminder that the file then holds a plaintext secret; keep its permissions
restricted and never share it (support ticket, public backup, etc.) with the URL still inside.
Enable delivery and choose a delivery mode#
In alerts.yml, set discord.enabled: true. delivery-mode: ALWAYS (the default) sends every
qualifying finding to Discord regardless of in-game staff presence; WHEN_NO_INGAME_STAFF sends
only when no eligible in-game staff member is online; HIGH_RISK_ONLY restricts delivery to
high-confidence/high-severity findings. discord.minimum-confidence/minimum-vl-delta filter
further underneath whichever mode you pick — see the full key reference linked above.
Role mentions#
Optionally enable discord.role-mention.enabled and set FLAGFORGE_DISCORD_STAFF_ROLE_ID to a
numeric Discord role ID (never a role name) to ping that one role on serious findings —
role-mention.minimum-confidence/minimum-incident-risk/evidence-classes gate this
independently (and more strictly) than ordinary delivery. FlagForge constructs Discord's
allowed_mentions so only that exact role can ever be pinged — no finding/check/player-derived
text can inject @everyone, @here, or an unintended mention.
Test it#
Start (or restart) the server, then run /ff discord test to send a clearly labeled test message
and confirm delivery (it never pings the mention role unless you've opted into
role-mention.mention-on-test), and /ff discord status to check queue health.
Delivery behavior#
Discord delivery runs on its own bounded async queue (discord.outbound-queue.* — see the full
key reference for exact sizing/timeouts):
- Aggregates repeated alerts for the same player/check within a short window into one message.
- Retries transient failures (network errors, timeouts, 5xx, 429 with its
Retry-Afterhint honored) with capped exponential backoff; never retries a permanent 4xx. - Opens a circuit breaker after repeated failures, so an outage cannot slow down or affect gameplay/detection/in-game alerts.
If discord.enabled is true but no webhook URL resolves, FlagForge disables Discord delivery only
and logs why — everything else keeps working normally. Every delivery attempt (success or failure)
is recorded in ff_alert_deliveries — see the Data Model page.