Setting up Grafana alerting for Discord usually results in cluttered messages filled with redundant JSON data or missing vital context. By default, native integrations send rigid formats that don't match team workflows.
You can fix this by routing alerts through Grafana's webhook contact point, applying custom notification templates, and formatting JSON payloads specifically for Discord webhooks. This approach lets you clean up noise, structure embeds, and highlight metrics that matter.
Why Default Discord Integrations Fall Short
Grafana includes a native Discord contact point integration, but it lacks flexibility. When multiple alerts fire simultaneously, the default layout often triggers wall-of-text notifications that obscure root causes. Engineers waste time clicking back into dashboards because the notification lacks specific threshold values or direct panel links.
Relying on default configurations also means you cannot adjust colors based on severity, truncate unhelpful metadata, or group related alerts logically. Building custom templates via the webhook receiver solves these layout constraints, giving you precise control over every character sent to your channel. Further journalism by Bloomberg highlights similar perspectives on the subject.
Configuring the Discord Webhook Endpoint
Before touching Grafana templates, you need a target channel endpoint in Discord.
- Open your Discord server settings and navigate to Integrations.
- Click Create Webhook and select the target text channel where alerts should land.
- Copy the generated Webhook URL to your clipboard. Keep this URL secret; anyone who has it can post messages to your channel.
Next, open your Grafana instance and navigate to Alerting & IRM > Contact points. Click + Add contact point, choose Webhook as the integration type, and paste your Discord Webhook URL into the target field.
Creating Notification Templates in Grafana
Grafana uses Go templates to process alert data. To structure a custom payload for Discord, you must create a dedicated notification template group.
Go to Alerting & IRM > Notification configuration > Templates, and click + New notification template. Name your template group descriptively, such as discord_custom_payload.
Inside the content block, define your custom template structure. Discord expects a specific JSON structure when utilizing rich embeds, typically containing a content string or an embeds array. A basic layout maps the alert status, title, and summary annotations directly into JSON format:
{
"username": "Grafana Alert Bot",
"embeds": [
{
"title": "{{ .CommonLabels.alertname }}",
"description": "{{ range .Alerts }}{{ .Annotations.summary }}{{ end }}",
"color": 15158332
}
]
}
This template extracts the primary alert name and pulls summary annotations from firing instances.
Applying Custom Payloads to the Webhook Contact Point
Once your template is saved, return to your Webhook contact point configuration. Scroll down to the optional settings where payload customization is handled.
- Locate the Custom Payload option.
- Enable custom payload formatting.
- Reference your template using Grafana template execution functions, or paste the structured JSON directly into the template body field.
When the Custom Payload option is active, standard title and message fields are bypassed, allowing your defined JSON structure to pass straight to the Discord API without interference.
Testing and Debugging Template Output
Grafana provides a built-in preview tool to verify template syntax before alerts hit production channels.
Navigate back to your template configuration and click Preview. You can load existing alert instances or input mock payload data to inspect the exact JSON string Grafana will generate. If your template contains syntax errors or mismatched brackets, the preview panel highlights the exact line numbers, letting you fix formatting bugs safely.
Frequently Asked Questions
Can I send images or graphs directly in Discord alerts?
Discord webhooks accept image URLs via embed structures, but Grafana's alert engine does not natively render and attach snapshot images inside webhook payloads without external storage configurations. Most teams include direct dashboard links in the alert description instead.
Why are my notification templates taking time to update?
Grafana synchronizes notification templates across background worker nodes. Changes can take one to two minutes to propagate through the Alertmanager.
How do I color-code Discord embeds based on alert states?
You can use conditional logic inside your Go templates ({{ if eq .Status "firing" }}...{{ else }}...{{ end }}) to dynamically change the decimal color value passed to the Discord embed JSON object.
