Troubleshoot Discord Webhooks

When to use this guide

Use this guide when configured Discord alerts do not arrive or do not mention the expected staff roles.

Check webhook settings

Webhook delivery is disabled by default and its URL starts empty. The remaining settings control when an enabled webhook sends and how delivery retries are handled.

• Identity and content: username defaults to FairPlay, with avatarUrl, serverName, content, and an embed sub-object for message shape.
• Mentions: suppressNotifications defaults to false, with allowedRoleIds as the explicit role-mention mechanism.
• Threshold: minimumVl defaults to 2.0, so violations below that level do not produce webhook output.
• Cooldown: cooldownMs defaults to 2000, throttling repeated deliveries.
• Transport: connectTimeoutMs defaults to 5000, readTimeoutMs defaults to 5000, maxRetries defaults to 3, and retryBaseDelayMs defaults to 1000.

Diagnostic sequence

1. Confirm enabled is true in the server’s webhook configuration.
2. Confirm a webhook URL is configured; keep it private and redact it from reports.
3. Compare the alert level with minimumVl; events below the threshold are not sent.
4. Allow the configured cooldown before testing repeated alerts.
5. For intermittent delivery, review connection/read timeouts, retry count, and retry delay.
6. If alerts arrive without expected mentions, review suppressNotifications and allowedRoleIds.

Next step

If alerts still do not arrive, review the server console for delivery errors and verify the URL and Discord webhook settings.