Skip to content

Discord webhook notifications

McProgression can send XP awards and losses, skill-level, Global Rank, and moderator profile-change events to Discord webhooks. The integration is disabled by default; nothing is sent until integrations.discord-webhooks.enabled is set to true and a valid webhook URL is configured. Individual XP-award messages are also off by default, so enabling the integration does not post a Discord message for every block, mob, or other XP action.

Configure channels

Create webhooks in Discord and put their URLs in plugins/McProgression/config.yml. Keep these URLs private: anyone who obtains one can post to its channel. Do not commit real webhook URLs to source control or include them in support logs.

Webhook usernames and default footer text follow branding.display-name. Set integrations.discord-webhooks.username to a non-empty value when you want a separate Discord name; an existing config with the old default McProgression also follows the branding setting.

Default embed titles, descriptions, footers, and field labels follow the configured language. If you customize an event's title, description, or footer, that text is kept as written; changing the language will not overwrite it. The player-facing chat announcements also support legacy & color codes. Their default format uses a white bracket and player name, the configured brand name in aqua, and the message in gray. Edit player-display.announcements.*.format to choose other colors or arrange the {branding}, {player_icon}, {player}, and {message} parts.

You can use separate channels.xp.url and channels.levels.url endpoints, or set the top-level url as a fallback. An event-specific url overrides both. The XP channel carries XP-award summaries and death-loss messages. The levels channel carries skill/global rank changes and moderator profile changes, which remain immediate regardless of the XP-award mode.

branding:
  display-name: "Levels"

integrations:
  discord-webhooks:
    enabled: true
    username: "" # Empty follows branding.display-name.
    avatar-url: ""
    timezone: Europe/Brussels
    time-format: "dd-MM-yyyy HH:mm:ss z"
    channels:
      xp:
        enabled: true
        url: "https://discord.com/api/webhooks/…"
      levels:
        enabled: true
        url: "https://discord.com/api/webhooks/…"
    xp-awarded:
      enabled: true
      mode: summary # off (default), individual, or summary
      summary-interval-seconds: 30
      max-pending-summaries: 100
    xp-loss:
      enabled: true
    skill-level-up:
      enabled: true
    skill-level-down:
      enabled: true
    global-rank-up:
      enabled: true
    profile-reset:
      enabled: true

Set xp-awarded.mode to choose how successful XP awards reach Discord:

  • off (recommended default) sends no XP-award posts. XP history remains available in McLeveling; this setting only controls Discord noise.
  • summary combines awards server-wide into one message per progression scope and skill for each time window. The default window is 30 seconds, so active players share the same digest instead of each producing their own post. Each digest reports total XP, award count, and distinct player count; mixed activities or worlds are labeled as such. This is an operational summary, not a per-player or event-by-event audit trail.
  • individual sends one detailed post for every award. Use this only temporarily for troubleshooting or on a low-volume server; block and mob activity can produce a high request rate.

Summaries are held in memory until the configured window ends and grouped only by scope and skill across the whole server. max-pending-summaries bounds the number of distinct groups held at once (default and hard maximum 100); if that limit is reached, additional events are omitted from Discord summaries and counted in a throttled server-log warning. When a bucket contains more than one source or world, the embed labels it multiple activities or multiple worlds. Unsent summaries are discarded when the plugin shuts down. The XP history ledger remains authoritative for player-level investigation and is unaffected by this Discord setting.

Individual XP event embeds include the player name and UUID, skill or General XP scope, source activity, amount, previous and new XP, level and Global Rank score, world, and a local timestamp. Server-wide summary descriptions support {players}, {amount}, {awards}, {progression}, {scope}, {skill}, {source}, and {world}. Death penalties have a separate XP-loss event with the death category, per-skill losses, General XP loss, and world. Its description supports {player}, {uuid}, {amount}, and {category}. Skill level-ups and Global Rank increases have separate embeds with before/after values. Moderator reset and reset-sync actions include the moderator, target, old/new Global Rank, sync summary, and any skill level decreases.

The level-up chat message can also include {player}, {skill}, {old_level}, {new_level}, {level}, {amount}, {old_xp}, {new_xp}, {source}, {world}, and {score}. Global Rank chat messages support {player}, {old_rank}, {rank}, {old_score}, and {score}.

Requests run asynchronously, are serialized through a bounded queue, and retry Discord rate-limit responses. queue-limit bounds queued requests (default 500). XP summaries are moved ahead of routine XP posts, and can replace queued individual XP posts if the queue is full; level/rank/moderator events are prioritized above summaries. If the queue remains full of equal or higher priority events, the new post is dropped and a throttled server-log warning reports queue depth and the cumulative drop count. On shutdown, a status line reports the counts seen at shutdown for delivered, dropped, aggregated, and pending summaries when there was work to report; it is not a final delivery receipt for a request that is still in flight. HTTP failures log only the status or error class; webhook URLs and tokens are never included. A server shutdown may discard queued but unsent notifications.

Server-owner recommendation: keep XP-award mode at off or use summary for routine operations. Reserve individual for short troubleshooting windows. Keep the XP and levels channels separate if moderators want progression milestones and admin actions without the frequent XP feed.