Configure Grafana OnCall OSS on Grafana Labs

Grafana OnCall integrations

Fri, 03 Apr 2026 19:43:06 +0000

Grafana OnCall integrations

An integration serves as the primary entry point for alerts that are processed by Grafana OnCall. Integrations receive alerts through a unique API URL, interpret them using a set of templates tailored for the specific monitoring system, and initiate escalations as necessary.

For more information about how to configure an integration, refer to Configure and manage integrations.

Understand the integration alert flow

An alert is received on an integration’s Unique URL as an HTTP POST request with a JSON payload (or via Inbound email for email integrations).
The incoming alert is routed according to the Routing Template.
Alerts are grouped based on the Grouping ID Template and rendered using Appearance Templates.
The alert group can be published to messaging platforms, based on the Publish to Chatops configuration.
The alert group is escalated to users according to the Escalation Chains selected for the route.
An alert group can be acknowledged or resolved with status updates based on its Behavioral Templates.
Users can perform actions listed in the Alert Workflow section.

Explore available integrations

Refer to Integration references for a list of available integrations and specific set up instructions.

Configure templates for OnCall OSS

Fri, 03 Apr 2026 19:43:06 +0000

Configure templates for OnCall OSS

Grafana OnCall OSS integrates with your monitoring systems using webhooks with JSON payloads. By default, these webhooks deliver raw JSON payloads. Grafana OnCall OSS applies a pre-configured alert template to modify these payloads into a more human-readable format. These templates are customizable, enabling you to format alerts and notify different escalation chains based on alert content.

Understand your alert payload

Alerts received by Grafana OnCall contain metadata as key-value pairs in a JSON object.

All alerts and alert groups in Grafana OnCall contain the following fields.

Title
Message
Image Url
Grouping Id
Resolved by source
Acknowledged by source
Source link

The following is an example of an alert initiated by Grafana Alerting and received by Grafana OnCall:

{
  "dashboardId": 1,
  "title": "[Alerting] Panel Title alert",
  "message": "Notification Message",
  "evalMatches": [
    {
      "value": 1,
      "metric": "Count",
      "tags": {}
    }
  ],
  "imageUrl": "https://grafana.com/static/assets/img/blog/mixed_styles.png",
  "orgId": 1,
  "panelId": 2,
  "ruleId": 1,
  "ruleName": "Panel Title alert",
  "ruleUrl": "http://localhost:3000/d/hZ7BuVbWz/test-dashboard?fullscreen\u0026edit\u0026tab=alert\u0026panelId=2\u0026orgId=1",
  "state": "alerting",
  "tags": {
    "tag name": "tag value"
  }
}

Map payloads to OnCall fields

Each field of an alert in OnCall is mapped to the JSON payload keys.

Grafana OnCall converts the JSON payload to specific alert fields. For example:

{{ payload.title }} -> Title
{{ payload.message }} -> Message
{{ payload.imageUrl }} -> Image Url

Behavioral mappings include:

{{ payload.ruleId }} -> Grouping Id
{{ 1 if payload.state == 'OK' else 0 }} -> Resolve Signal

Types of templates

Alert templates allow you to format any alert fields recognized by Grafana OnCall. You can customize default alert templates for all the different notification methods.

Note
For conditional templates, the output should be True to be applied, for example {{ True if payload.state == 'OK' else False }}

Routing template

Routing templates determine how alerts are routed to different escalation chains based on alert content.

These are conditional templates, output should be True.

Appearance templates

Appearance templates customize how alerts are displayed across various platforms, including the web, Slack, MS Teams, SMS, phone calls, emails, and mobile app push notifications.

You can use appearance templates to define Title, Message, and Image URL depending on the notification method.

Title, Message, Image URL for Web
Title, Message, Image URL for Slack
Title, Message, Image URL for MS Teams
Title, Message, Image URL for Telegram
Title for SMS
Title for Phone Call
Title, Message for Email
Title, Message for push notifications

Behavioral templates

Behavioral templates control alert behaviors such as grouping, auto-resolution, and acknowledgment.

Grouping Id: Applied to every incoming alert payload after routing. Determines how alerts are grouped.
Autoresolution: Automatically resolves alert groups with a status of Resolved by source (conditional template).
Auto acknowledge: Automatically acknowledges alert groups with a status of Acknowledged by source (conditional template).
Source link: Customizes the URL link provided as the alert’s source.

Tip
As a best practice, add Playbooks, useful links, or checklists to the alert message.

Integration templates

Integration templates are applied to alerts that originated from a specific integration to define alert rendering and behavior.

Grafana OnCall provides pre-configured default Jinja templates for supported integrations. For any monitoring system not available in the Grafana OnCall integrations list, configure a Webhook integration and configure your templates as needed.

Edit templates

Open the Integration page for the desired integration.
Navigate to the Templates section and click Edit to see previews of all templates for the integration.
Select the template to edit and click Edit. The template editor will open with three columns: example alert payload, the template itself, and the rendered result.
Choose a Recent Alert group to see its latest alert payload. Click Edit to modify this payload.
Alternatively, click Use custom payload to write your own payload and see its rendering.
Press Control + Enter in the editor to view suggestions.
Click Cheatsheet in the second column for inspiration.
For messenger templates, click Save and open Alert Group in ChatOps to see how the alert renders in the messenger. Note: The alert group must exist in the messenger to preview the template.
Click Save to save the template.

Escalation chains and routes for OnCall OSS

Fri, 03 Apr 2026 19:43:06 +0000

Escalation chains and routes for OnCall OSS

This topic provides information about escalation chains, steps, routes, and instructions for configuring them in Grafana OnCall OSS.

In Grafana OnCall, configuring proper alert routing and escalation ensures that alerts are directed to the right teams and handled promptly.

Alerts often need to be sent to different teams or channels depending on their severity or specific alert details. Set up routes and escalation chains to customize and automate escalation according to each teams workflows.

Routes

Routes determine which escalation chain should be triggered for a specific alert group based on the details of the alert. A route uses Routing Templates to determine the escalation chain and notification channels.

When an alert is received, its details are evaluated against the route’s routing template, and the first matching route determines how the alert will be handled.

Example:

Trigger the Database Critical escalation chain for alerts with {{ payload.severity == "critical" and payload.service == "database" }}
Use a different route for alerts with the payload {{ "synthetic-monitoring-dev-" in payload.namespace }}, selecting the Security escalation chain.

Create and manage routes

To create or manage a route:

Navigate to the Integrations page.
Click Add route to create a new route, or Edit to modify an existing one.
In the Routing Template section, define conditions that will determine which alerts this route applies to. The template must evaluate to True for the route to be selected.
Select the appropriate escalation chain from the Escalation Chain dropdown. If an escalation chain doesn’t exist, click Add new escalation chain, which will open a new tab for chain creation. After creating the chain, return to the routes page and click Reload list to update the available options.
In the Publish to ChatOps section, select the relevant communication channels for this route (Slack, Teams, etc.). Ensure ChatOps integrations are configured before using this feature.
Arrange the routes by clicking the up/down arrows to prioritize the routes as needed. The order determines which route is evaluated first.
To delete a route, click the three dots on the route and select Delete Route.

Label-based routing

Note
This feature is available exclusively on Grafana Cloud.

You can use the labels variable in your routing templates to evaluate based on alert group labels. This provides additional flexibility in routing alerts based on both labels and payload data.

Example:

{{ labels.foo == "bar" or "hello" in labels.keys() or payload.severity == "critical" }}

Escalation Chains

Escalation chains define the series of actions taken when an alert is triggered. The chain continues until a user intervenes by acknowledging, resolving, or silencing the alert.

You can configure different escalation chains for different workflows. For example, one chain might notify on-call users immediately, while another sends a low-priority message to a Slack channel.

Create and manage escalation chains

Navigate to the Escalation Chains page.
Click New escalation chain to create a new chain.
Enter a unique name and assign the chain to a team.
Click Add escalation step to define the steps for this chain (e.g., notifying users, waiting, escalating).
To edit an existing chain, click Edit. To remove a chain, click Delete.

Note

The name must be unique across the organization. Alert groups inherit the team from the integration, not the escalation chain.

Linked integrations and routes are shown in the right panel. Changes to the escalation chain impact all associated integrations and routes.

Types of escalation steps

Wait: Pause for a specified time before moving to the next step. You can add multiple wait steps for longer intervals.
Notify users: Notify individual users or groups.
Notify users from on-call schedule: Send notifications to users from a defined on-call schedule.
Notify all team members: Notify all users in a team.
Resolve incident automatically: Immediately resolve the alert group with the status Resolved automatically.
Notify Slack channel members: Notify users in a Slack channel based on their OnCall profile preferences.
Notify Slack user group: Notify all members of a Slack user group.
Trigger outgoing webhook: Activate an outgoing webhook.
Round robin notifications: Notify users sequentially, with each user receiving different alert groups.
Time-based escalation: Continue escalation only if the current time falls within a specific range (e.g., during working hours)
Threshold-based escalation: Escalate only if a certain number of alerts occur within a specific time frame.
Repeat escalation: Loop the escalation chain up to five times.
Declare incident (non-default routes): Available only in Grafana Cloud. Declares an incident with a specified severity. Limited to one incident per route at a time. Additional alerts are grouped into the active incident, and up to five are listed as incident context.

Note
The Notify Slack channel members and Notify Slack user group steps are designed to notify OnCall-registered users via their configured notification rules. To avoid spamming a Slack channel with alert group notifications, notifications are not sent in the alert group Slack thread.

Notification types

When an escalation step notifies a user, it follows their personal notification settings, which are configured in their user profile.

Each user can have two sets of notification rules:

Default Notifications: For standard alerts.
Important Notifications: For high-priority alerts.

Each escalation step allows you to select which set of notification rules to use. For more information about user notification rules, refer to the Notifications section.

Configure SMS & call routing with Grafana OnCall

Fri, 03 Apr 2026 19:43:06 +0000

Configure SMS & call routing with Grafana OnCall

This guide walks you through how to configure a system that enables you to page on-call personnel in Grafana OnCall by calling or texting a specific phone number.

Configure the basic setup in this guide to route SMS and voice calls to OnCall using a Twilio phone number and a Webhook integration. You can further customize your configuration to send different alerts to different escalation chains based on the contents of the text or voice call.

Before you begin

To complete the steps in this guide, ensure you have the following:

For Grafana Cloud users: A Grafana Cloud account. If you haven’t already, sign up for Grafana Cloud.
For OSS users: Notification routing must be configured using either Grafana Cloud or a third-party provider, such as Twilio. Refer to the Grafana OnCall open source guide for more information.
Grafana OnCall user with administrator privileges and notification settings configured.
Twilio account: Sign up for Twilio.

Note
While OSS users have the option to use Grafana Cloud for phone and SMS routing, it is not required. If you decide to use Grafana Cloud for notification delivery, be aware that charges may apply. For more information, refer to our billing documentation.

Basic set up

In the basic set up, you’ll create an integration in OnCall and configure a phone number in Twilio. This set up allows you to receive alerts in OnCall from SMS messages or phone calls made to your Twilio phone number. We’ll expand this setup as we go.

Grafana OnCall set up

To complete the Grafana OnCall portion of the configuration, ensure you have:

Grafana OnCall user account with administrator privileges.
Configured notification settings for your user to test functionality along the way.

If you need to set these up first, refer to the Grafana OnCall documentation.

Set up webhook integration

Create a new integration to establish an endpoint for receiving alerts and connecting them to routes and escalation chains. The generic webhook integration accepts any payload and allows for customization of how the payload is handled in OnCall.

To create the integration:

In Grafana Cloud, navigate to Alerts & IRM -> OnCall -> Integrations.
Click + New Integration.
Choose Webhook (Generic) as the integration type.
Provide a name, description, and optionally assign it to a team.
Note the integration URL for future use in Twilio.

Add an Escalation Chain

An escalation chain defines a sequence of notifications and other actions once an alert has been received in OnCall.

Create a simple escalation chain to directly notify your user for testing during the set up process:

Go to Alerts & IRM -> OnCall -> Escalation chains.
Click + New Escalation chain.
Provide a name and click Create Escalation Chain.
For step 1, choose Notify users and select your user.

Later, you can customize the escalation chain as needed.

Connect and test the Escalation Chain

Connect the escalation chain to the newly created integration and then test that the set up is working correctly.

Return to the Webhook integration.
In the integration details, under Routes, assign the new escalation chain as the Default route using the dropdown.
Click Send demo alert and verify that you receive a notification as expected.
Resolve the demo alert.

Next, switch to Twilio to set up the other side of the integration.

Twilio set up

A Twilio account is required to complete the steps in this section. If you haven’t already,sign up for Twilio

In this section, you’ll set up the following:

A Twilio phone number
Twilio Studio Flows to send information as an alert to Grafana OnCall.

Set up Studio Flow

Twilio Studio flows allow you to create custom workflows to execute when a phone call or SMS message is received.

In this guide, we’ll use Twilio’s Studio Flow to capture alert information from SMS messages and phone calls to send it to Grafana OnCall:

In Twilio, navigate to Develop -> Studio -> Flows. If Studio isn’t visible, select Explore Products and navigate to Studio under the Developer Tools section.
Select Create new Flow, enter a Flow name, and click Next.
Select Import from JSON and click Next.
Import the provided JSON, which can be found in the Grafana OnCall GitHub repository.
Replace <YOUR_INTEGRATION_URL> (Lines 54 and 156) with the webhook integration URL from Grafana OnCall.
After adding your webhook URL, click Next.
Review the flow and click Publish to make the flow available for use.

Understand your flow

The flow you created has two paths:

SMS Path: Accepts incoming messages and forwards their contents to Grafana OnCall via the Webhook URL, including the sender’s phone number.
Voice Path: Converts voice calls to text and sends them to the Webhook integration in Grafana OnCall.

Buy a Twilio phone number

Purchase a phone number in Twilio to receive calls and messages:

Go to Develop -> # Phone Numbers -> Manage -> Buy a number. If you don’t see Phone Numbers, select Explore Products -> Super Network -> Phone Numbers.
Search for a number in your desired country code, select one, and buy it.
Once purchased, the number will be available in Active Numbers.

Note
Some countries and regions may require additional information to purchase a phone number such as address, contact person, etc.

Configure the phone number

Configure your Twilio phone number to use the Studio Flow you created.

In Develop -> Phone Numbers -> Manage -> Active Numbers, select the purchased number.
Configure Voice: Set the dropdown A call comes in to Studio Flow. Then select the flow we created.
Configure Messaging: Set the dropdown A message comes in to Studio Flow. Then select the flow we created.
Save the configuration.

Test and troubleshoot

Test configuration via SMS:

Send an SMS message to the purchased number and verify that you receive an “Alert sent” success notification.
Shortly after that, verify that you received a notification from Grafana OnCall using your configured method.

Test configuration via phone call:

Call the purchased number, follow the instructions to describe your alert, and verify that you hear a message that the alert was sent successfully.
Confirm that you receive a notification from Grafana OnCall using your configured method.

If you encounter issues:

Ensure the correct integration URL is configured.
Check the configuration of your Twilio Studio Flow. Confirm that “A message comes in” and “A call comes in” are configured correctly for the Phone number.
Review execution logs in Twilio Studio. In Studio -> Flows, select the flow you created and view Execution Log.
Review Grafana OnCall escalation log. Verify if an alert group was created in OnCall. If not, the alert didn’t make it to the URL. If there is an alert group, view the escalation log to review what happened.

Basic setup complete

You’ve completed the basic setup to receive alerts via SMS and phone calls in Grafana OnCall. Explore the advanced configuration section to learn how to further enhance your set up by routing alerts to different escalation chains.

Advanced SMS & call routing configuration

With the basic set up in place, you can add more optionality and automation by configuring SMS and voice calls to present a list of options to select from. The selected option then determines which route an alert is sent to in Grafana OnCall.

To accomplish this, you’ll configure an additional route and escalation chain attached to your Twilio Webhook integration in Grafana OnCall. Then, in Twilio, expand the Studio Flow to present options to the caller. This set up can be easily expanded upon to handle more routes.

Create an additional Escalation Chain

To create an escalation chain:

Go to Alerts & IRM -> OnCall -> Escalation chains.
Click + New Escalation chain.
Provide a name and click Create Escalation Chain.
For step 1, choose Notify users and select your user as the recipient. You can mark this one Important to differ from the previous one.

Later you can edit the escalation chain to match your on-call process.

Add a Route

A route in Grafana OnCall is a configurable part of an integration that enables you to specify how an alert is handled depending on it’s payload. It involves sequentially matched rules defined as Jinja2. The first rule that evaluates to true for an incoming alert payload determines how the alert is routed.

In our set up, we’ll maintain the existing escalation chain from the Basic Setup as our default route and add our newly created escalation chain to a new route.

To create a route and route alerts to the newly created escalation chain:

Return to the Twilio Webhook integration and select Add Route.
Click Edit template to open the template editor.
Enter {{ "abc" in payload.target.lower()}} to define custom logic for selecting the escalation chain based on alert content, then click Save.
Select the newly created escalation chain from the drop-down at step 3.

This template indicates that if the alert payload sent from Twilio contains the target field with a value of abc, this route will be selected. Later, you can customize this logic to suit your specific routing needs, such as by team, service, or region.

Now Grafana OnCall can route alerts from Twilio to different escalation chains based on their content.

Add a Studio Flow in Twilio

Similar to the Studio Flow created in the Basic setup, you’ll create a more complex Flow in Twilio to present options to the caller.

Create a new Flow for more complex handling:

In Twilio, navigate to Develop -> Studio -> Flows. If Studio isn’t visible, select Explore Products and navigate to Studio under the Developer Tools section.
Select Create new Flow, enter a Flow name, and click Next.
Select Import from JSON and click Next.
Import the provided JSON, which can be found in the Grafana OnCall GitHub repository.
Replace <YOUR_INTEGRATION_URL> (Lines 54 and 156) with the webhook integration URL from Grafana OnCall.
After adding your webhook URL, click Next.
Review the flow and click Publish to make the flow available for use.

Understand your flow

This flow maintains the same two paths from the Basic set up while incorporating additional steps to prompt the user to specify the target for the alert and include validation checks to ensure the accuracy of provided values.

SMS Path: Accepts incoming messages and forwards their contents to Grafana OnCall via the Webhook URL, including the sender’s phone number.
Voice Path: Converts voice calls to text and sends them to the Webhook integration in Grafana OnCall.

Reconfigure the Twilio phone number

Update your Twilio phone number configuration to use the more complex Flow created in the previous step:

In Develop -> Phone Numbers -> Manage -> Active Numbers, select the purchased number.
Configure Voice: Set the dropdown A call comes in to Studio Flow. Then select the new flow.
Configure Messaging: Set the dropdown A message comes in to Studio Flow. Then select the new flow.
Save the configuration.

Test and troubleshoot

Test the SMS and voice call paths to verify proper routing and that you receive notifications from OnCall.

Next steps

Now that you’ve completed the initial set up, you can customize your Grafana OnCall routes and escalation chains to meet your specific routing requirements. Utilize the graphical editor available in Twilio Studio Flow to fine-tune your alert routing.