Azure Monitor integration#

IncidentRelay accepts Azure Monitor Common Alert Schema notifications through a native incoming route.

Endpoint:

CopyPOST /api/integrations/azure-monitor

Only the Common Alert Schema is accepted. Legacy provider-specific Azure Monitor webhook schemas are intentionally rejected so routing, severity and lifecycle behavior stay deterministic.

Create the IncidentRelay route#

Create a route with:

CopySource: Azure Monitor

The default grouping field is:

Copy["azure_alert_id"]

Save the route and copy the generated webhook URI immediately. The URI contains HTTP Basic credentials:

Copyhttps://incidentrelay:<ROUTE_TOKEN>@incidentrelay.example.com/api/integrations/azure-monitor

IncidentRelay uses the fixed username incidentrelay and the route intake token as the Basic-auth password. Bearer authentication with the same route token is also accepted for Logic Apps, curl, or other clients that can set custom headers.

Configure an Azure Monitor Action Group#

In Azure Monitor, create or edit an Action Group and add a Webhook action.

Use the webhook URI generated by IncidentRelay and enable Common Alert Schema for that action.

Do not choose Secure webhook for this setup. Secure webhook uses Microsoft Entra ID, while this integration authenticates the native Webhook action with HTTP Basic credentials embedded in the URI.

Azure defines the schema at the action level, so Common Alert Schema must be enabled on the webhook action itself.

Lifecycle#

IncidentRelay maps data.essentials.monitorCondition as follows:

alertId is the preferred deduplication key. Azure sends the same alert instance identity through its lifecycle, so a resolved notification updates the existing IncidentRelay alert instead of creating another alert.

If alertId is unavailable, IncidentRelay falls back to originAlertId and then to a stable generated key.

Severity mapping#

Labels and routing#

IncidentRelay exposes common Azure metadata as labels, including:

Copyazure_alert_id
azure_alert_rule
azure_alert_rule_id
azure_origin_alert_id
azure_monitor_condition
azure_severity
azure_signal_type
azure_monitoring_service
azure_target_resource_id
azure_configuration_item
azure_resource_group
azure_resource_type
azure_subscription_id
event_link

Values from data.customProperties are also copied into matcher-friendly labels. This is the recommended way to provide routing metadata such as:

Copy{
  "team": "sre",
  "service": "checkout",
  "environment": "production"
}

A team or oncall_team custom property can participate in the normal team-routing behavior.

Test request#

Copycurl -X POST 'https://incidentrelay.example.com/api/integrations/azure-monitor' \
  -H 'Content-Type: application/json' \
  -u 'incidentrelay:ROUTE_TOKEN' \
  -d '{
    "schemaId": "azureMonitorCommonAlertSchema",
    "data": {
      "essentials": {
        "alertId": "/subscriptions/example/providers/Microsoft.AlertsManagement/alerts/example-1",
        "alertRule": "Checkout API latency",
        "severity": "Sev1",
        "signalType": "Metric",
        "monitorCondition": "Fired",
        "monitoringService": "Platform",
        "configurationItems": ["checkout-api"],
        "description": "p95 latency exceeded 2 seconds"
      },
      "customProperties": {
        "team": "sre",
        "service": "checkout",
        "environment": "production"
      }
    }
  }'

To test resolution, send the same alertId with:

Copy"monitorCondition": "Resolved"

Troubleshooting#

• 401 Route intake token is required: verify that the Action Group uses the exact generated URI and that the username is incidentrelay.
• 400 Route source must be azure_monitor: the credential belongs to a route with another source.
• 400 Azure Monitor Common Alert Schema is required: enable Common Alert Schema on the Webhook action.
• Fired and Resolved create separate alerts: verify that Azure sends the same alertId for the alert instance.
• Route/service matching does not work: inspect customProperties and normalized labels in Alert details.

Microsoft documentation: Azure Monitor Common Alert Schema and Action Groups.