Documentation Grafana Cloud Alerts and IRM IRM Configure Integrations Webhooks Incoming webhooks OnCall webhooks

Configure OnCall incoming webhooks

OnCall incoming webhooks allow external monitoring systems to send alert data directly to Grafana IRM. You can use webhooks to integrate with monitoring tools that don’t have native integrations in IRM.

About OnCall incoming webhooks

OnCall webhooks receive HTTP requests from external systems and convert them into alerts that can be:

• Processed through your defined routing rules
• Grouped with related alerts
• Escalated to the appropriate teams
• Displayed with customized templates

Webhook formats

There are two incoming webhooks integration options:

• Webhook – Receives and displays the raw JSON payload exactly as it is sent from the external system.

• Formatted Webhook – Parses alert payloads that follow a recognized format, enabling structured alerting and improved usability.

Recognized fields for formatted webhooks

The following fields can be included in a formatted webhook payload:

While none of these fields are required, including them improves alert handling and display.

Set up a webhook

Create an OnCall incoming webhook integration

1. In Grafana IRM, go to the Integrations tab
2. Click Monitoring systems and select either Webhook or Formatted Webhook
3. Click + New integration
4. Provide a name and description for the webhook
5. Assign the integration to a team
6. Click Create Integration
7. Copy the Webhook URL provided on the integration page

Configure the external system

1. In your monitoring tool, navigate to the webhook configuration settings
2. Paste the Webhook URL from Grafana IRM into the designated field
3. Configure the payload format to match Grafana IRM’s expected structure
4. Save the configuration and send a test alert

Example webhook payload

To send a test webhook using cURL:

bash Copy

curl -X POST \
https://a-prod-us-central-0.grafana.net/integrations/v1/formatted_webhook/m12xmIjOcgwH74UF8CN4dk0Dh/ \
-H 'Content-Type: application/json' \
-d '{
    "alert_uid": "08d6891a-835c-e661-39fa-96b6a9e26552",
    "title": "The whole system is down",
    "image_url": "https://upload.wikimedia.org/wikipedia/commons/e/ee/Grumpy_Cat_by_Gage_Skidmore.jpg",
    "state": "alerting",
    "link_to_upstream_details": "https://en.wikipedia.org/wiki/Downtime",
    "message": "Smth happened. Oh no!"
}'

Customize alert routing

Once your webhook is set up, customize how alerts are processed:

• Define routing templates – Specify how alerts are categorized
• Set up grouping ID templates – Group related alerts into alert groups
• Modify appearance templates – Adjust how alert notifications appear in UI and messaging apps
• Assign escalation chains – Ensure alerts reach the correct responders

Test and validate

After configuring your webhook integration, it’s important to verify that alerts are being received and processed as expected. There are two ways to test your setup:

Use the demo alert feature

You can use demo alerts to verify basic connectivity. To send a simple demo alert, click Send demo alert from the integration you want to test.

Test full webhook functionality

For a comprehensive test, including grouping, routing, and template processing, send real HTTP requests to your webhook URL:

1. Use a tool like cURL (see the example webhook payload above) to send alerts to your webhook URL.
2. Send multiple test alerts with the same alert_uid to confirm that grouping works as expected.
3. Monitor incoming alerts in Grafana IRM to verify correct routing, grouping, and escalation.
4. Adjust your integration settings as needed to ensure alerts are processed and escalated according to your requirements.