Integrations & Plugins

There are several different ways to integrate other alert sources into Alerta.

Firstly, existing integrations with well known monitoring tools like Nagios, Zabbix and Sensu make use of the Alerta API and demonstrate how to build integrations with other monitoring tools.

Secondly, there are built-in webhooks for AWS Cloudwatch, Pingdom, PagerDuty, Google Stackdriver, Prometheus Alertmanager and more which provide ‘out-of-the-box’ integrations for some of the most popular monitoring systems available.

Thirdly, alert severity indicators or widgets can be placed on any web page using oEmbed for easy integration with existing dashboards.

Lastly, plugins can be used to quickly and easily forward alerts to or notify other systems like Slack or Hipchat.

Integrations 

Core 

There are a few core integrations which have been developed to showcase how easy it is to get alerts or events from other tools into Alerta. They are:

Nagios Event Broker - forward host/service check results with suppression during downtime
InfluxData Kapacitor - forward alerts for metric anomalies and dynamic thresholds
Zabbix Alert Script - forward problems, acknowledged and OK events
Sensu Plugin - forward Sensu events
Riemann Plugin - generate alerts from thresholds defined against metric streams
Kibana Logging - log alerts to Elasticsearch for historical visualisation of alert trends

Contrib 

There are several more integrations available in the contrib repo which may be useful. They are:

Amazon SQS - receive alerts from SQS that were sent using the SNS core plugin
E-mail - send emails after a hold-time has expired (requires the `AMQP`_ message queue core plugin)
Opsweekly - query Alerta to generate Opsweekly reports
Pinger - generate ping alerts from list of network resources being pinged
SNMP Trap - generate alerts from SNMPv1 and SNMPv2 sources
Supervisor - trigger alerts and heartbeats based on process deamon events
Syslog Forwarder - receive RFC 5424, RFC 3164 syslog and Cisco syslog messages
URL monitor - trigger alerts from web service query responses

External 

Some third-party monitoring tools have built-in support for Alerta. They are:

elastalert - alerting on anomalies, spikes, or other patterns of interest from data in Elasticsearch
netdata - a system for distributed real-time performance and health monitoring
Tick Stack - designed to handle metrics and events using Telegraf, InfluxDB, Chronograf, and Kapacitor

Bi-directional 

Bi-directional integration is where the system integrating with Alerta provides information that enables Alerta to link back to the originating system, either via an external link or simply a hostname and reference ID.

There are several examples of this two-way integration and they mostly take advantage of the flexible nature of the the tags and attributes alert attributes which can be used to keep track of the external reference.

Usage

In it’s simplest form, pass the URL of the external system that generated the alert in an attribute called externalUrl (or similar):

$ alerta send -E ... --attribute externalUrl=https://my.example.com/go?id=1234

Better still, surroud the URL with HTML markup to make the link clickable in the web UI:

$ alerta send -E ... --attribute externalUrl='<a href="https://my.example.com/go?id=1234">ref 1234</a>'

Examples

The following is a list of integrations, webbhooks and plugins that highlight the use of bi-directional integration in different ways.

AWS Cloudwatch webhook - includes the SNS subscription confirmation link in the text of the alert
Zabbix integration & plugin - TBC
Grafana webhook - includes rule and image links in Grafana alert attributes if available
NewRelic webhook - includes incident and runbook links in NewRelic alerts
PagerDuty webhook - includes the incident URL in alert history text when status changes
Prometheus webhook - includes external and generator URLs in the alert attributes
Zabbix integration - includes moreInfo link back to Zabbix console event trigger page in alert attribute

Webhooks 

Webhooks are a way of integrating with other systems by triggering HTTP callbacks to the Alerta server API when an event occurs.

Note

If authentication is enforced, then an API key is needed to access the alerta API programatically and use the webhooks.

Please follow this page for more information on how to pass your api-key : https://docs.alerta.io/en/latest/authentication.html#api-keys

AWS CloudWatch 

Alerta can be configured to receive AWS CloudWatch alarms by subscribing the Alerta API endpoint to an SNS topic.

For details on how to set this up see the Sending Amazon SNS Messages to HTTP/HTTPS Endpoints page and in the Endpoint input box append /webhooks/cloudwatch to the Alerta API URL.

Example AWS CloudWatch Webhook URL

https://alerta.example.com/api/webhooks/cloudwatch

Example AWS CloudWatch Webhook URL with authentication

https://alerta.example.com/api/webhooks/cloudwatch?api-key=xxxxx

Grafana 

Alerta can be configured to receive Grafana alerts by adding a webhook endpoint to the Notification Channels.

For details on how to set this up see Grafana webhook page and in the Endpoint URL input box append /webhooks/grafana to the Alerta API URL.

Example Grafana Webhook URL

https://alerta.example.com/api/webhooks/grafana

The following parameters can be set in the url: environment, event_type, group, origin, service, severity, timeout

Example Grafana Webhook URL with parameters

https://alerta.example.com/api/webhooks/grafana?api-key=xxx&environment=Production&service=Web&timeout=3600

Graylog 

TBC

New Relic 

Alerta can be configured to receive New Relic incidents by adding a webhook endpoint to the Notification Channels.

For details on how to set this up see New Relic webhook page and in the Endpoint URL input box append /webhooks/newrelic to the Alerta API URL.

Example New Relic Webhook URL

https://alerta.example.com/api/webhooks/newrelic

Example New Relic Webhook URL with authentication

https://alerta.example.com/api/webhooks/newrelic?api-key=xxxxx

PagerDuty 

Alerta can be configured to receive PagerDuty incident-based webhooks – any change to the status or assigned_to_user of an incident will cause an outgoing message to be sent.

For details on how to set this up see the PagerDuty webhook page and where it requires the webhook URL append /webhooks/pagerduty to the Alerta API URL.

Example PagerDuty Webhook URL

https://alerta.example.com/api/webhooks/pagerduty

Example PagerDuty Webhook URL with authentication

https://alerta.example.com/api/webhooks/pagerduty?api-key=xxxxx

Pingdom 

Alerta can be configured to receive Pingdom URL check alerts by adding a webhook alerting endpoint that calls the Alerta API.

For details on how to set this up see the Pingdom webhook page and in the webhook URL input box append /webhooks/pingdom to the Alerta API URL.

Example Pingdom Webhook URL

https://alerta.example.com/api/webhooks/pingdom

Example Pingdom Webhook URL with authentication

https://alerta.example.com/api/webhooks/pingdom?api-key=xxxx

Prometheus Alertmanager 

Alerta can be configured as a webhook receiver in Alertmanager.

For details on how to set this up see the Prometheus Config GitHub Repo

Riemann 

Alerta can be configured to receive Riemann events. The integration makes no assumptions about the format of the Riemann events and consumes standard events. If events are decorated with additional metadata (eg. tags, environment, group, etc) then these will be used.

Example Riemann Webhook URL

https://alerta.example.com/api/webhooks/riemann

Example Riemann Webhook URL with authentication

https://alerta.example.com/api/webhooks/riemann?api-key=xxxxx

SeverDensity 

Alerta can be configured to receive SeverDensity alerts by adding a webhook endpoint to the Notification Preferences.

For details on how to set this up see SeverDensity webhook page and in the Endpoint URL input box append /webhooks/serverdensity to the Alerta API URL.

Example SeverDensity Webhook URL

https://alerta.example.com/api/webhooks/serverdensity

Example SeverDensity Webhook URL with authentication

https://alerta.example.com/api/webhooks/serverdensity?api-key=xxxxx

Slack 

TBC

Google Stackdriver 

Alerta can be configured to receive Google Stackdriver incidents by adding a webhook endpoint to the notifications configuration.

For details on how to set this up see Stackdriver webhook page and in the ENDPOINT URL input box append /webhooks/stackdriver to the Alerta API URL.

Example Stackdriver Webhook URL

https://alerta.example.com/api/webhooks/stackdriver

Example Stackdriver Webhook URL with authentication

https://alerta.example.com/api/webhooks/stackdriver?api-key=xxxxx

Telegram 

Alerta can be configured to receive Telegram callback queries from the inline buttons in the `Telegram Bot`_ plugin.

For details on how to set this up see `Telegram Bot`_ page and for the TELEGRAM_WEBHOOK_URL setting append /webhooks/telegram to the Alerta API URL.

Example Telegram Webhook URL

https://alerta.example.com/api/webhooks/telegram

Example Telegram Webhook URL with authentication

https://alerta.example.com/api/webhooks/telegram?api-key=xxxxx

Widgets 

Add an alert severity indicator (aka. widget) to any dashboard using the Oembed API endpoint. The severity indicator is coloured with the maximum severity for that alert query filter and has a count for the total number of matching alerts for each severity.

Multiple severity indicators can be placed on the same page each for a different environment, service or group. See the example oembed web page.