Skip to content

Discord Integration

JonathanLA edited this page Nov 11, 2026 · 1 revision

Discord Integration

ServerGuard supports two independent Discord webhooks: a public channel and an admin channel. Either, both, or neither may be set.

What each channel receives

Public channel (discordWebhookUrl)

Player-facing events only. Safe to share with your whole community.

Event Example
Player joined βœ… Erik (76561198064360681) joined
Player left πŸ‘‹ Erik (76561198064360681) left
Player kicked πŸšͺ Erik (76561198064360681) was kicked β€” wrong password
Player auto-banned β›” Erik (76561198064360681) was auto-banned β€” too many strikes
Player died πŸ’€ Erik (76561198064360681) died at [-1234, 567] β€” killed by a Troll
Player shouted πŸ“£ **Erik** shouted: they're at the docks!
Raid started βš”οΈ **The Horde Is Attacking** has started! Location: X:123, Z:-456
Raid paused / resumed ⏸️ **The Horde Is Attacking** is paused β€” no players in the event area.
Raid ended βœ… **The Horde Is Attacking** is over!
Server starting ⏳ **Server is starting...**
Server ready βœ… **The server has started, you may now login.**
Server stopping πŸ›‘ **Server is shutting down.**
First boss kill (2.1) βš”οΈ Alice and Bob defeated **The Elder** for the first time! (real bosses only; staff left out)

The three server-lifecycle messages have no on/off setting β€” like raid alerts, they follow discordWebhookUrl.

"Starting" and "started" are two separate messages on purpose. The plugin loads long before the world does, so "starting" fires immediately on boot, and "you may now login" only once the world is loaded and location generation has finished β€” which on a brand-new seed can be several minutes later. Players who join on the first message would just be refused.

If world generation somehow never completes, no public "started" message is sent; a timeout warning goes to the admin channel instead after 15 minutes.

The shutdown message needs a graceful stop (console stop, service stop, window close). A SIGKILL, power loss, or host crash gives the plugin no chance to post.

Admins are hidden from this channel. Their joins, leaves, deaths, and kicks all route to the admin channel instead. Players never see admins coming and going.

To show staff logins publicly, set discordPublicStaffLogins: true (2.5). Owners' and moderators' joins (joined as owner, joined as moderator) and leaves then go to both channels. Their deaths and kicks still go to the admin channel only.

Admin channel (discordWebhookUrlAdmin)

Curated moderation events. Use a private channel that only moderators can see.

Event Example
Server boot πŸš€ ServerGuard online v2.5.0 enforce=ON requireHmac=ON req/allow/ban=1/29/0 modset=8ce8906e
Staff dev command run server-side (2.0) πŸ”§ **Erik (765…)** (owner) ran server command \skiptime 1800``
Cheat-flagged items reported (2.0) πŸ§ͺ **Erik (765…)** is carrying **3** cheat-flagged item(s): SwordIron, Wood x64
Debug fly detected (2.0) πŸ•ŠοΈ Erik (765…) is using debug fly (public channel)
Moderator tried an unlisted dev command (2.0) 🚫 **Erik (765…)** (moderator) tried dev command \spawn` β€” not in `moderatorDevcommands``
Hot-reload πŸ”„ allowed_mods.yaml reloaded β€” req=1 allow=29 ban=0
Counted violation ⚠️ Erik (765…) violated DevcommandAttempt (1/3) β€” fly
Informational rule πŸ‘ Erik (765…) triggered HashMismatch (informational β€” not counted) β€” Jotunn
Auto-ban β›” Auto-banned Erik (765…) (threshold reached)
Manual kick πŸšͺ Disconnected Erik (765…) β€” Kicked by admin.
Admin command πŸ›  Erik (765…) ran sg kick someone
Admin player events πŸ›‘ Erik (765…) joined as admin
First ping (if enabled) πŸ›° Erik (765…) first ping: 42 ms
Session avg ping πŸ›° Erik (765…) session ping avg: 38 ms (24 samples)
Daily summary A one-paragraph digest at the configured UTC hour
Progress credited (2.1) πŸ† **The Elder** credited to Alice (765…), Bob (765…) β€” nearby without damage: Carl
Progress the server never granted (2.1) ⚠️ **Erik (765…)** arrived carrying progress this server never granted (Eikthyr)
Progress reset by a mod (2.2) ♻️ Progress reset (BlΓ³t RagnarΓΆk): cleared 42 entries on 9 characters.
Inventory sealed / unsealed / expired (2.2) πŸ”’ Sealed the inventories of 3 account(s) … / πŸ”“ Unsealed …
Sealed player brought items from elsewhere (2.2) πŸ”’ **Erik (765…)** (Erik) arrived with 2 item type(s) from another world - removed (…): SwordIron x1, Wood x30
Watch page (2.3) πŸ›°οΈ Watch page opened by **Erik (765…)** (key ab12cd) from 1.2.3.4 Β· πŸ”‘ … created watch-page key Β· πŸ› οΈ … ran sg kick … (watch page) Β· 🚨 Watch page: 10 wrong keys from 1.2.3.4 - blocked
API test listener (2.2, sg test listen) πŸ§ͺ API event ProgressCredited(765…, **Erik**, defeated_eikthyr)

See Personal Progression for when progress posts appear (progressionDiscordPosts).

Verbose mirror (optional, discordVerboseMirror: true)

Forwards every ServerGuard log line to the admin channel. Very noisy β€” debug only.

Creating webhooks

In Discord:

  1. Open your server settings β†’ Integrations β†’ Webhooks.
  2. Create a new webhook in the channel where you want events to appear.
  3. Copy the URL.
  4. Paste into settings.yaml:
discordWebhookUrl: 'https://discord.com/api/webhooks/...'        # public
discordWebhookUrlAdmin: 'https://discord.com/api/webhooks/...'   # admin
  1. Save. Hot-reload picks it up β€” no restart needed.

If only one URL is configured, all events that would route to the other channel are silently suppressed.

Daily summary

A coroutine fires once per UTC day and posts a digest:

πŸ“Š Daily summary
2026-05-29 00:00 UTC β†’ 2026-05-30 00:00 UTC
β€’ Joins: 14
β€’ Leaves: 12
β€’ Kicks: 3
β€’ Auto-bans: 1
Top kick reasons:
  – wrong password (2)
  – had a mod that isn't allowed (BiggerBackpack) (1)

Configure:

dailySummaryEnabled: true
dailySummaryHourUtc: 0       # 0..23 - hour at which the post fires
dailySummaryChannel: admin   # public | admin | both

If no events occurred, the scheduled post is silently skipped (no spam).

Friendly reason wording

The public channel uses non-technical language. Internal rule names like HmacInvalid, DisallowedMod, ChallengeMismatch are translated:

  • HmacInvalid β†’ "wrong password"
  • CompanionMissing β†’ "missing the required companion mod"
  • RequiredModMissing β†’ "missing a required mod (Name)"
  • DisallowedMod β†’ "had a mod that isn't allowed (Name)"
  • BannedMod β†’ "had a banned mod (Name)"
  • HashMismatch β†’ "mod file doesn't match the server's copy (Name)"
  • CharacterNameLimitExceeded β†’ "tried to use too many characters"

The admin channel keeps the technical rule name so moderators can correlate to log lines.

Stopping a noisy channel

If you accidentally point both URLs at the same channel and don't want duplicates: set dailySummaryChannel: admin (or public) instead of both, and don't enable discordVerboseMirror.

See also

Clone this wiki locally