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-After hint 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.