Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow Alertingbreadcrumb arrow Configure notificationsbreadcrumb arrow Configure contact pointsbreadcrumb arrow MQTT
Grafana Cloud Enterprise Open source

Configure MQTT notifications

Use the MQTT integration in contact points to send alert notifications to your MQTT broker.

Configure MQTT for a contact point

To create a contact point with MQTT integration, complete the following steps.

  1. Navigate to Alerts & IRM -> Alerting -> Contact points.
  2. Click + Add contact point.
  3. Enter a name for the contact point.
  4. From the Integration list, select MQTT.
  5. Enter your broker URL in the Broker URL field. Supports tcp, ssl, mqtt, mqtts, ws, wss schemes. For example: tcp://127.0.0.1:1883.
  6. Enter the MQTT topic name in the Topic field.
  7. (Optional) Configure additional settings.
  8. Click Save contact point.

For more details on contact points, including how to test them and enable notifications, refer to Configure contact points.

Required Settings

OptionDescription
Broker URLThe URL of the MQTT broker.
TopicThe topic to which the message will be sent.

Optional Settings

OptionDescription
Message formatIf set to json (default), the notification message uses the default JSON payload.
If set to text, the notification message is fully customizable.
MessageDepends on the Message format option.
In json format, defines only the message field of the default JSON payload.
In text format, defines the entire custom payload.
This field supports notification templates.
Client IDThe client ID to use when connecting to the MQTT broker. If blank, a random client ID is used.
UsernameThe username to use when connecting to the MQTT broker.
PasswordThe password to use when connecting to the MQTT broker.
QoSThe quality of service to use when sending the message. Options are At most once, At least once, and Exactly once.
RetainIf set to true, the message will be retained by the broker.
TLSTLS configuration options, including CA certificate, client certificate, and client key, and disable certificate verification.
Disable resolved messageEnable this option to prevent notifications when an alert resolves.

Default JSON payload

If the Message format option is json (the default), the payload is like this example.

JSON 
{
  "receiver": "My MQTT integration",
  "status": "firing",
  "orgId": 1,
  "alerts": [
    {
      "status": "firing",
      "labels": {
        "alertname": "High memory usage",
        "team": "blue",
        "zone": "us-1"
      },
      "annotations": {
        "description": "The system has high memory usage",
        "runbook_url": "https://myrunbook.com/runbook/1234",
        "summary": "This alert was triggered for zone us-1"
      },
      "startsAt": "2021-10-12T09:51:03.157076+02:00",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "https://play.grafana.org/alerting/1afz29v7z/edit",
      "fingerprint": "c6eadffa33fcdf37",
      "silenceURL": "https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT2%2Cteam%3Dblue%2Czone%3Dus-1",
      "dashboardURL": "",
      "panelURL": "",
      "values": {
        "B": 44.23943737541908,
        "C": 1
      }
    },
    {
      "status": "firing",
      "labels": {
        "alertname": "High CPU usage",
        "team": "blue",
        "zone": "eu-1"
      },
      "annotations": {
        "description": "The system has high CPU usage",
        "runbook_url": "https://myrunbook.com/runbook/1234",
        "summary": "This alert was triggered for zone eu-1"
      },
      "startsAt": "2021-10-12T09:56:03.157076+02:00",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "https://play.grafana.org/alerting/d1rdpdv7k/edit",
      "fingerprint": "bc97ff14869b13e3",
      "silenceURL": "https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT1%2Cteam%3Dblue%2Czone%3Deu-1",
      "dashboardURL": "",
      "panelURL": "",
      "values": {
        "B": 44.23943737541908,
        "C": 1
      }
    }
  ],
  "groupLabels": {},
  "commonLabels": {
    "team": "blue"
  },
  "commonAnnotations": {},
  "externalURL": "https://play.grafana.org/",
  "version": "1",
  "groupKey": "{}:{}",
  "message": "**Firing**\n\nLabels:\n - alertname = T2\n - team = blue\n - zone = us-1\nAnnotations:\n - description = This is the alert rule checking the second system\n - runbook_url = https://myrunbook.com\n - summary = This is my summary\nSource: https://play.grafana.org/alerting/1afz29v7z/edit\nSilence: https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT2%2Cteam%3Dblue%2Czone%3Dus-1\n\nLabels:\n - alertname = T1\n - team = blue\n - zone = eu-1\nAnnotations:\nSource: https://play.grafana.org/alerting/d1rdpdv7k/edit\nSilence: https://play.grafana.org/alerting/silence/new?alertmanager=grafana&matchers=alertname%3DT1%2Cteam%3Dblue%2Czone%3Deu-1\n"
}

Body

If the Message format option is json (the default), the payload contains the following fields.

KeyTypeDescription
receiverstringName of the contact point
statusstringCurrent status of the alert, firing or resolved
orgIdnumberID of the organization related to the payload
alertsarray of alertsAlerts that are triggering
groupLabelsobjectLabels that are used for grouping, map of string keys to string values
commonLabelsobjectLabels that all alarms have in common, map of string keys to string values
commonAnnotationsobjectAnnotations that all alarms have in common, map of string keys to string values
externalURLstringExternal URL to the Grafana instance sending this webhook
versionstringVersion of the payload
groupKeystringKey that is used for grouping
messagestringCustom message configured in Message (Optional Settings).
Supports notification templates; the output is formatted as a string.

Note

When using the json Message format, only the message field of the JSON payload is customizable, and its output is formatted as a string.

To customize the full payload in text or JSON format, use the text format and define a custom payload.

Alert object

The Alert object represents an alert included in the notification group, as provided by the alerts field.

KeyTypeDescription
statusstringCurrent status of the alert, firing or resolved.
labelsobjectLabels that are part of this alert, map of string keys to string values.
annotationsobjectAnnotations that are part of this alert, map of string keys to string values.
startsAtstringStart time of the alert.
endsAtstringEnd time of the alert, default value when not resolved is 0001-01-01T00:00:00Z.
valuesobjectValues that triggered the current status.
generatorURLstringURL of the alert rule in the Grafana UI.
fingerprintstringThe labels fingerprint, alarms with the same labels will have the same fingerprint.
silenceURLstringURL to silence the alert rule in the Grafana UI.
dashboardURLstringA link to the Grafana Dashboard if the alert has a Dashboard UID annotation.
panelURLstringA link to the panel if the alert has a Panel ID annotation.
imageURLstringURL of a screenshot of a panel assigned to the rule that created this notification.

Custom payload

When you set the Message format option to text, you can customize the entire payload of the MQTT message.

In this mode, the Message option defines the entire payload. It supports notification templates and can generate notification messages in plain text, JSON, or any custom format.

For examples of templates that produce plain text or JSON messages, refer to notification template examples.