Contact Points

Configure notification destinations for Grafana alerts

Contact points define where alert notifications are sent. They represent integrations with external systems like email, Slack, PagerDuty, and many others.

Contact Point Structure

A contact point can contain multiple integrations (receivers) that share the same name:

Contact Point

interface EmbeddedContactPoint {
  uid: string;              // Unique identifier
  name: string;             // Contact point name (shared across integrations)
  type: NotifierType;       // Integration type
  settings: object;         // Type-specific configuration
  disableResolveMessage: boolean;
  provenance?: string;      // 'file' | 'api' | undefined
}

type GrafanaNotifierType =
  | 'email'
  | 'slack'
  | 'pagerduty'
  | 'webhook'
  | 'discord'
  | 'teams'
  | 'opsgenie'
  | 'telegram'
  | 'victorops'
  | 'pushover'
  | 'sensugo'
  | 'googlechat'
  | 'threema'
  | 'prometheus-alertmanager'
  | 'dingding'
  | 'kafka'
  | 'wecom'
  | 'webex'
  | 'mqtt'
  | 'oncall'
  | 'sns';

Integration Configuration

Email

{
  "uid": "email-1",
  "name": "ops-team",
  "type": "email",
  "settings": {
    "addresses": "[e-mail],[e-mail]",
    "singleEmail": false
  },
  "disableResolveMessage": false
}

settings.addresses · string · required

Comma-separated list of email addresses

settings.singleEmail · boolean · default: "false"

Send a single email with all alerts (true) or separate emails (false)

Slack

{
  "uid": "slack-1",
  "name": "engineering",
  "type": "slack",
  "settings": {
    "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX",
    "recipient": "#alerts",
    "username": "Grafana",
    "icon_emoji": ":bell:",
    "icon_url": "",
    "mentionChannel": "here",
    "mentionUsers": "",
    "mentionGroups": "",
    "title": "{{ .CommonLabels.alertname }}",
    "text": "{{ range .Alerts }}{{ .Annotations.description }}{{ end }}"
  },
  "disableResolveMessage": false
}

settings.url · string · required

Slack webhook URL (incoming webhook)

settings.recipient · string

Channel name (e.g., #alerts) or user (e.g., @username)

settings.mentionChannel · string

Mention channel: here, channel, or empty

settings.mentionUsers · string

Comma-separated user IDs to mention

PagerDuty

{
  "uid": "pd-1",
  "name": "oncall",
  "type": "pagerduty",
  "settings": {
    "integrationKey": "${PAGERDUTY_KEY}",
    "severity": "critical",
    "class": "grafana-alert",
    "component": "monitoring",
    "group": "infrastructure",
    "summary": "{{ .CommonLabels.alertname }}"
  },
  "secureFields": {
    "integrationKey": true
  },
  "disableResolveMessage": false
}

settings.integrationKey · string · required

PagerDuty integration key (stored securely)

settings.severity · string

Severity level: critical, error, warning, info

Webhook

{
  "uid": "webhook-1",
  "name": "custom-system",
  "type": "webhook",
  "settings": {
    "url": "https://example.com/webhook",
    "httpMethod": "POST",
    "username": "",
    "password": "",
    "authorization_scheme": "Bearer",
    "authorization_credentials": "${API_TOKEN}",
    "maxAlerts": 0,
    "title": "{{ .CommonLabels.alertname }}",
    "message": "{{ .CommonAnnotations.summary }}"
  },
  "disableResolveMessage": false
}

settings.url · string · required

Webhook endpoint URL

settings.httpMethod · string · default: "POST"

HTTP method: POST, PUT

settings.authorization_scheme · string

Authorization scheme: Bearer, Basic, or custom

Microsoft Teams

{
  "uid": "teams-1",
  "name": "devops",
  "type": "teams",
  "settings": {
    "url": "https://outlook.office.com/webhook/...",
    "title": "{{ .CommonLabels.alertname }}",
    "message": "{{ range .Alerts }}{{ .Annotations.description }}{{ end }}",
    "sectiontitle": "Alert Details"
  },
  "disableResolveMessage": false
}

Discord

{
  "uid": "discord-1",
  "name": "monitoring",
  "type": "discord",
  "settings": {
    "url": "https://discord.com/api/webhooks/...",
    "avatar_url": "",
    "use_discord_username": false,
    "message": "{{ .CommonAnnotations.summary }}",
    "title": "{{ .CommonLabels.alertname }}"
  },
  "disableResolveMessage": false
}

Secure Fields

Sensitive data (API keys, passwords) are stored securely:

{
  "uid": "slack-1",
  "name": "team",
  "type": "slack",
  "settings": {
    "url": "${SLACK_WEBHOOK_URL}",  // Reference to secure storage
    "recipient": "#alerts"
  },
  "secureFields": {
    "url": true  // Indicates this field is encrypted
  }
}

Secure fields:

• Are encrypted at rest
• Cannot be read via API (only written)
• Use ${VAR_NAME} syntax in provisioning
• Show as true in secureFields when set

Notification Options

Disable Resolve Messages

{
  "disableResolveMessage": true
}

When true, only firing alerts are sent. Resolution notifications are suppressed.

Notification Templates

Use Go templates to customize notification content:

Common Variables

// Available in all templates
{{ .Status }}              // firing or resolved
{{ .CommonLabels }}        // Labels common to all alerts
{{ .CommonAnnotations }}   // Annotations common to all alerts
{{ .GroupLabels }}         // Labels used for grouping
{{ .ExternalURL }}         // Link to Grafana
{{ .Alerts }}              // List of all alerts
{{ .Alerts.Firing }}       // List of firing alerts
{{ .Alerts.Resolved }}     // List of resolved alerts

// Available in {{ range .Alerts }}
{{ .Status }}              // Alert status
{{ .Labels }}              // All labels
{{ .Labels.alertname }}    // Specific label
{{ .Annotations }}         // All annotations
{{ .StartsAt }}            // When alert started
{{ .EndsAt }}              // When alert ended
{{ .GeneratorURL }}        // Link to panel/rule
{{ .Fingerprint }}         // Unique identifier

// Title with alert name
"title": "{{ .CommonLabels.alertname }}"

// Summary with count
"summary": "{{ len .Alerts.Firing }} alerts firing"

// List all alerts
"message": "{{ range .Alerts }}
  Alert: {{ .Labels.alertname }}
  {{ .Annotations.description }}
{{ end }}"

// Conditional logic
{{ if gt (len .Alerts.Firing) 0 }}
  Firing: {{ len .Alerts.Firing }}
{{ end }}

Contact Point Metadata

With Status

interface ContactPointWithMetadata {
  name: string;
  integrations: Integration[];
  
  // Metadata
  numberOfPolicies: number;    // How many policies use this
  receiverStatus?: {           // Delivery status
    active: boolean;
    errorCount: number;
    notifiers: NotifierStatus[];
  };
}

interface NotifierStatus {
  name: string;
  lastNotifyAttempt: string;
  lastNotifyAttemptDuration: string;
  lastNotifyAttemptError?: string;
  sendResolved?: boolean;
}

Provisioning Contact Points

Provisioning File

# conf/provisioning/alerting/contactpoints.yaml
apiVersion: 1

contactPoints:
  - orgId: 1
    name: ops-team
    receivers:
      - uid: email-ops
        type: email
        settings:
          addresses: [e-mail]
        disableResolveMessage: false
      
      - uid: slack-ops
        type: slack
        settings:
          url: ${SLACK_WEBHOOK}
          recipient: '#ops'
          title: '{{ .CommonLabels.alertname }}'
        disableResolveMessage: false

// Location: pkg/services/provisioning/alerting/contact_point_types.go
type ContactPointV1 struct {
    OrgID     int64
    Name      string
    Receivers []ReceiverV1
}

type ReceiverV1 struct {
    UID                   string
    Type                  string
    Settings              map[string]interface{}
    DisableResolveMessage bool
}

Backend Components

Contact Point Definition

// Location: pkg/services/ngalert/api/tooling/definitions
type EmbeddedContactPoint struct {
    UID                   string
    Name                  string
    Type                  string
    DisableResolveMessage bool
    Settings              *simplejson.Json
    Provenance            string
}

type Receiver struct {
    Name                    string
    EmailConfigs            []*EmailConfig
    PagerdutyConfigs        []*PagerdutyConfig
    SlackConfigs            []*SlackConfig
    WebhookConfigs          []*WebhookConfig
    OpsGenieConfigs         []*OpsGenieConfig
    // ... other integration types
}

Validation

Contact points are validated before being saved:

1. Type Validation

   Integration type must be supported

2. Settings Validation

   Required settings for the integration type must be provided

3. Name Validation

   Name must be unique within the organization

4. Template Validation

   Notification templates must be valid Go templates

5. URL Validation

   Webhook URLs and other URLs must be valid

Testing Contact Points

Grafana provides a test feature to verify configuration:

POST /api/alertmanager/grafana/config/api/v1/receivers/test

Body:
{
  "name": "test-receiver",
  "grafana_managed_receiver_configs": [
    {
      "uid": "test-1",
      "name": "test-receiver",
      "type": "slack",
      "settings": {
        "url": "https://hooks.slack.com/services/...",
        "recipient": "#test"
      }
    }
  ],
  "alert": {
    "labels": { "alertname": "TestAlert" },
    "annotations": { "description": "This is a test" }
  }
}

Best Practices

Use meaningful names

Name contact points after the team or purpose (e.g., backend-team, critical-alerts, ops-pagerduty).

Group related integrations

Use multiple integrations in one contact point for notifications that should go to multiple places together.

Customize notification content

Use templates to make notifications informative and actionable. Include:

• Alert name and severity
• Relevant metric values
• Runbook links
• Dashboard links

Test before deploying

Always test contact points before using them in production notification policies.

Secure sensitive data

Use secure fields for API keys, tokens, and passwords. Never commit secrets to version control.

Handle resolve messages appropriately

Only disable resolve messages if the integration doesn’t support them or they’re not useful.

Troubleshooting

Notifications not being sent

• Check notification policy routes to this contact point
• Verify integration credentials are correct
• Check contact point status for errors
• Review alertmanager logs

Template errors

• Validate Go template syntax
• Check that referenced labels/annotations exist
• Test with the contact point test feature

Integration-specific issues

• Slack: Verify webhook URL and channel name
• Email: Check SMTP configuration in grafana.ini
• PagerDuty: Confirm integration key is correct
• Webhook: Check endpoint is accessible and accepts POST

Related Resources

Notification Policies

Route alerts to contact points

Alert Rules

Create rules that generate alerts

Notification Templates

Customize notification content

Overview

Understand the alerting architecture