Generic Webhook Alert Source

The Generic Webhook Alert Source lets Rootly ingest alerts from tools that send JSON objects or flat, form-encoded HTTP webhooks. Rootly maps fields from each event to an alert, routes it to the right responder, and triggers downstream automation. Use it when your alerting tool doesn’t have a dedicated Rootly integration, when you’re ingesting alerts from custom or internal services, or when you want a single, unified pattern for handling webhook-based signals across multiple sources.

Compatible Alerting Tools

Use this source for tools that send an HTTP POST with a JSON object or a supported form-encoded body, including:

Application performance & error tracking — BugSnag, AppOptics, Coralogix
Infrastructure & log monitoring — Sumo Logic, Elastic, Chronosphere, Nagios, PRTG
Uptime & synthetic monitoring — Pingdom, uptime.com, Checkly, Cronitor, Runscope
Security & threat detection — CrowdStrike, Expel, Cloudflare
Data quality & observability — Monte Carlo

It also works for internal services, custom monitoring jobs, scheduled scripts, and any system you build in-house that needs to page an on-call responder. If your tool has a dedicated Rootly integration, prefer that — native sources reduce setup time and ship with vendor-specific field mappings. The Generic Webhook Alert Source is the right choice when no native integration exists.

How It Works

The Generic Webhook Alert Source gives you a webhook endpoint URL that your external system POSTs alert events to. When a request arrives, Rootly:

Authenticates the request using the Bearer Token configured for the source.
Parses the payload and extracts the fields you mapped — title, description, identifier, state, routing target.
Creates or updates an alert based on the External Identifier. If Rootly already has an alert with the same identifier, follow-up events update it; otherwise a new alert is created.
Routes the alert to the target you specified, either from the URL or from the payload itself.
Triggers alert workflows, which can create incidents, page on-call, post to Slack, or run any other downstream action you’ve configured.

Webhook events are processed asynchronously. The POST returns quickly; the alert appears in Rootly shortly after.

Before You Begin

Before creating a Generic Webhook Alert Source, make sure you have:

Access to create alert sources in Rootly
A tool that can send POST requests with a JSON object or flat form-encoded body
A plan for how alerts should be routed after ingestion
The fields you want Rootly to extract, such as:
- Alert title
- Description
- External identifier
- Alert state
- Routing target

Send JSON objects with Content-Type: application/json, or use Content-Type: application/x-www-form-urlencoded for form-encoded bodies. In production, the Generic Webhook Alert Source uses these endpoint patterns:

Base endpoint: POST https://webhooks.rootly.com/webhooks/incoming/generic_webhooks
Fixed target endpoint: POST https://webhooks.rootly.com/webhooks/incoming/generic_webhooks/notify/<type>/<id>

Use the base endpoint with Alert Routes or payload-based target mappings for JSON and form-encoded bodies. Use the notify endpoint only when both the target type and target ID are included in the URL.

Installation

Create the Generic Webhook Alert Source

Go to the new alert source page and locate Generic Webhook Alert Source.

Generic Webhook Alert Source on the alert source page

You will be prompted to name the source.

Authenticate incoming requests

Rootly verifies inbound generic webhook requests using a Bearer Token — a static secret you provide in either of these forms:

Authorization: Bearer <secret>
secret as a URL query parameter

If the secret is missing or invalid, Rootly rejects the request. Prefer the header form when your sending tool supports it — query parameters tend to be captured in proxy and load-balancer access logs.Example request (header form, recommended):

curl -X POST \
  -H "Authorization: Bearer <YOUR_BEARER_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "High CPU on web-01",
    "description": "CPU > 90% for 5 minutes",
    "external_id": "monitor-12345",
    "state": "triggered"
  }' \
  https://webhooks.rootly.com/webhooks/incoming/generic_webhooks

Example request (query-parameter form):

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "title": "High CPU on web-01", "external_id": "monitor-12345", "state": "triggered" }' \
  "https://webhooks.rootly.com/webhooks/incoming/generic_webhooks?secret=<YOUR_BEARER_SECRET>"

Map the incoming payload fields

Generic webhook sources do not require a strict vendor-specific payload shape. Configure how Rootly should interpret the incoming payload by mapping fields from the JSON object or decoded form fields.At a minimum, you should map a field for the alert title so alerts are easy to identify in Rootly.Depending on your use case, you may also want to map:

Alert description
External URL
External identifier
Alert state
Notification target type
Notification target ID

Follow the instructions shown on the Generic Webhook creation page to configure these mappings.

Notification target ID must be Rootly’s internal resource ID — not a team name, service slug, or any human-readable identifier. Open the service, team, or escalation policy in Rootly and copy the ID from its edit page. Using a name or slug is a common cause of alerts that ingest successfully but never route. See Routing Alerts for the full mapping guidance.

Payload Formats

The Generic Webhook Alert Source accepts JSON objects and flat URL-encoded form bodies. Existing JSON payloads and field mappings continue to work.

Format	Content Type	Values Available to Mappings
JSON object	`application/json`	JSON values, including nested objects, arrays, numbers, and booleans
URL-encoded form	`application/x-www-form-urlencoded`	Decoded field names and string values

For form requests:

Declare Content-Type: application/x-www-form-urlencoded and use UTF-8; an explicit charset=UTF-8 parameter is also supported.
URL-encode field names and values, including spaces, literal + signs, &, and non-ASCII characters.
Use unique field names; if a name is repeated, Rootly keeps the last value.
Use JSON when you need nested objects or arrays; form names such as labels[team] remain literal field names.

For a literal field named labels[team], use $['labels[team]'] in a JSONPath mapping or {{ alert.data['labels[team]'] }} in an Alert Fields Liquid mapping. Confirm the extracted value in the payload preview. For example, this body:

monitor_id=monitor-12345&title=Checkout+%26+API&state=triggered&priority=1

is available to field mappings as:

{
  "monitor_id": "monitor-12345",
  "title": "Checkout & API",
  "state": "triggered",
  "priority": "1"
}

Map $.title to the title, $.monitor_id to the external identifier, and $.state to the state. For sources using Alert Fields, select the decoded fields from the payload preview when defining Liquid mappings. To send this example, use the complete webhook URL from your source configuration and its Bearer secret:

curl --request POST "<YOUR_WEBHOOK_URL>" \
  --header "Authorization: Bearer <YOUR_BEARER_SECRET>" \
  --header "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
  --data-urlencode "monitor_id=monitor-12345" \
  --data-urlencode "title=Checkout & API" \
  --data-urlencode "state=triggered" \
  --data-urlencode "priority=1"

Configure auto-resolution with resolved as the recovery state for this example, then send the same monitor_id with state=resolved to close the alert. To combine repeated trigger events, enable deduplication with the same stable monitor identifier.

Authentication

Rootly authenticates inbound webhook requests with a Bearer Token — a static secret sent in the Authorization header, or as a secret query string parameter on the webhook URL. Prefer the header form when your sending tool supports it — query parameters tend to be captured in proxy and load-balancer access logs, so they’re more exposure-prone than a header. Either form is simple to set up: paste the secret into your sending tool and you’re done. Code samples for Bearer Token authentication live in Installation. Use the same authentication configuration for JSON and form requests. Send the Bearer secret in the Authorization header or URL query parameter; a form field named secret is payload data.

Mapping Payload Fields

Rootly doesn’t require a specific schema. You map fields from your sending tool’s JSON object or decoded form payload to Rootly’s alert fields during source creation. A typical payload from a monitoring tool:

{
  "alert_title": "High CPU on web-01",
  "alert_description": "CPU > 90% for 5 minutes",
  "external_id": "monitor-12345",
  "state": "triggered",
  "service": "web-api"
}

Map those fields to Rootly’s alert fields in the source configuration:

Rootly Field	Mapped From	Purpose
Title	`alert_title`	Headline shown on the alert
Description	`alert_description`	Body text on the alert
External Identifier	`external_id`	Stable key Rootly uses to match follow-up events to the same alert
State	`state`	Lifecycle state — drives auto-resolution when a recovery event arrives
Routing Target	`service`	Which service, team, or escalation policy receives the alert

The External Identifier is what Rootly uses to match recovery events back to the original alert when auto-resolution is configured. Map it to whatever field your sending tool uses as the alert’s persistent ID (monitor_id, incident_id, alert_uuid, etc.) so that a follow-up “resolved” event can close the original alert instead of being ignored. See the Installation guide for the field-mapping UI walkthrough.

Routing Alerts

Choose how Rootly should select the destination for alerts from this source.

Use Alert Routes

Create an Alert Route that includes this source, then configure conditions and destinations for its routing rules.Use the base webhook endpoint for this setup. Rootly evaluates the decoded payload against your rules and selects the destination, so the sender does not need to include Rootly target IDs.

Route By URL

Include the target type and ID directly in the webhook URL Rootly generates:

POST https://webhooks.rootly.com/webhooks/incoming/generic_webhooks/notify/<type>/<id>

Use this when every alert from this source should always route to the same target — one service, one team, or one escalation policy. Cleanest setup, and you do not need to map the target type and target ID in the payload mapping step.

Webhook URL configuration with notification target

Route By Payload

Send the target type and ID in the payload and let Rootly extract them via field mappings, as in this JSON example:

{
  "alert_title": "Database slow query",
  "notification_target_type": "service",
  "notification_target_id": "8c4a5e91-1b2d-4c3e-9f6a-7d8b2c5e9a01"
}

The notification_target_id is the Rootly resource’s internal ID — open the service, team, or escalation policy in Rootly and copy the ID from its edit page. Names and slugs aren’t accepted in this field.Form senders can supply the same target type and ID as string fields; map those decoded fields in the source configuration.Use this when a single source needs to route alerts to different targets depending on the event — useful when your monitoring tool already tags events by service or team, or when you want the routing decision to come from the event payload itself. Advanced payloads can also include a Rootly notification target object directly in the JSON body.

Common target types: service, group (or team), escalationPolicy.

Automatically Added Labels

Every alert ingested from a Generic Webhook Alert Source is automatically tagged with a source_name label whose value is your alert source’s name parameterized — lowercased, with spaces and other non-alphanumeric characters replaced by hyphens. For example, an alert source named Harbor Image Scan (c1) adds source_name:harbor-image-scan-c1 to every alert it produces. This label is the canonical way to differentiate alert sources of the same type in Alert Workflows. The source condition in a workflow matches by source type (for example, generic_webhook), so if you have multiple Generic Webhook sources, the workflow can’t tell them apart from the source condition alone — pair it with a source_name label condition (using contains any of) to scope each workflow to a specific source instance. See Scoping to a specific source instance for the workflow-side setup.

Test the Source

Send a test alert

After setup, send a test alert from your observability provider and confirm that Rootly receives and processes it as expected.

Confirm the alert was processed correctly

A successful test should confirm that:

The webhook request reaches Rootly
The payload is parsed correctly
The alert title and other mapped fields are populated as expected
The alert routes to the correct target
The alert appears in Rootly

Rootly processes webhook events asynchronously, so the alert may appear shortly after a successful request.If the request is authenticated correctly but the payload is missing expected fields, Rootly may still ingest the event, but the alert may not contain the data you intended.

Auto-Resolution

Auto-resolution lets Rootly close alerts when your external system sends a recovery or resolved-style webhook event. This is useful when your monitoring platform sends one event when an issue starts and another when it clears — by configuring the correct identifier and state fields, Rootly recognizes the related alert and applies the resolution logic you defined. Auto-resolution depends on the resolution configuration stored on the source. For the Generic Webhook Alert Source, that configuration is based on:

The field that identifies the alert
The field that represents its state
The value that should be treated as resolved

These settings allow Rootly to handle follow-up webhook events consistently when your source sends a recovery or cleared event.

Configure Auto-Resolution

Map the identifier field

Configure a field mapping for the external identifier in your webhook payload.This value should stay consistent across events for the same alert so Rootly can associate follow-up webhook events with the correct alert.

Map the state field

Configure a field mapping for the alert state in your webhook payload.This field should represent whether the alert is active, cleared, resolved, or in another lifecycle state used by your source system.

Define the resolved state value

Set the state value that Rootly should treat as resolved.In most cases, this is an exact match against the value you configure, such as resolved, recovered, or ok.

Enable auto-resolution

Turn on auto-resolution for the Generic Webhook Alert Source after your identifier and state mappings are configured.Once enabled, Rootly uses those mappings and the resolved-state value as part of the source’s resolution configuration.

Important Notes

Auto-resolution depends on the field mappings configured for the source
The identifier field and state field should be stable and predictable in your incoming webhook payload
If your payload does not include the expected values, Rootly may still ingest the alert event, but it may not resolve the alert the way you intend
Some teams may also use payload-driven alert status fields separately from auto-resolution mapping
Teams using newer alert field or resolution-rule configuration may manage this behavior through that newer configuration path instead of the legacy generic webhook mapping flow

From Alert to Incident

Alerts created through this source behave like any other Rootly alert — they’re regular signals you can drive any of Rootly’s alert-driven automation off of:

Create incidents automatically based on alert content, severity, or service
Page on-call responders through escalation policies
Post notifications to Slack, Microsoft Teams, or email
Trigger downstream workflows that update runbooks, status pages, ticketing systems, or run custom scripts

The webhook source ingests the alert; alert workflows decide what the alert means and what should happen next.

Troubleshooting

Rootly returns 400 for a form-encoded request

Confirm that the request declares Content-Type: application/x-www-form-urlencoded, uses UTF-8, and URL-encodes its field names and values. Other declared character sets and invalid UTF-8 values are rejected. Use the Generic Webhook Alert Source for this format; dedicated integration sources retain their own payload requirements.

Rootly returns 401 Unauthorized

The most common cause is a missing or mismatched Bearer token. Confirm:

The Authorization: Bearer <secret> header is present on the request (or the secret query string parameter is set)
The secret matches the one shown in the source configuration in Rootly

The webhook returns 200 but no alert appears in Rootly

Webhooks process asynchronously, so check again after a few seconds. If the alert still doesn’t appear:

Verify the Title field mapping points at a non-empty field in the payload
Check the source’s recent activity in Rootly to confirm the payload was received
Confirm the routing target referenced in the URL or payload exists and isn’t archived

Alerts appear but the fields are empty

The field mapping is pointing at JSON paths that don’t exist in the incoming payload. Capture a real payload using a request inspector (RequestBin, webhook.site, or a local server), compare it against your mapping, and update the JSON paths to match the actual structure.

Recoveries create new alerts instead of closing the original

The External Identifier isn’t mapped to a stable, unique value, so the resolved event can’t be matched back to the original alert. Map it to whatever field your sending tool uses as the persistent ID (monitor_id, incident_id, alert_uuid, etc.) so trigger and recovery events share the same identifier.

Recovery events don't resolve the original alert

Either the recovery payload has a different External Identifier than the original alert, or the State field isn’t mapping to the exact resolved value you configured. See Auto-Resolution for the matching rules.

One source needs to route to multiple teams

Use the base endpoint with Alert Routes to select destinations from payload conditions, or map target type and target ID fields supplied by the sender. Both options support JSON and form-encoded bodies.

Frequently Asked Questions

Does my monitoring tool need a native Rootly integration?

No. The Generic Webhook Alert Source accepts JSON objects and supported form-encoded POST bodies. Native integrations reduce setup time by providing vendor-specific field mappings.

What's the difference between an alert and an incident in Rootly?

Alerts are signals — discrete events from your monitoring stack. Incidents are coordinated response — the incident channel, the timeline, the retrospective. One incident may be informed by many alerts. The webhook source creates alerts; alert workflows decide when an alert should escalate to an incident.

Can I use one webhook source for multiple tools?

You can, but it’s cleaner to create one source per sending tool. Separate sources make it easier to route alerts differently per tool, attribute issues during troubleshooting, and manage authentication independently.

How do I send the same alert to multiple targets?

Route the alert to a single target with the webhook, then use an alert workflow to fan out the response — page on-call, post to Slack, create an incident, update a status page. The webhook ingests the alert; the workflow decides what should happen next.

What if my tool only supports query-string secrets, not Authorization headers?

Both work. Rootly accepts the Bearer secret either as the Authorization: Bearer <secret> header or as a secret query string parameter on the webhook URL.

Can I customize the alert title beyond what the payload contains?

The webhook source maps from existing payload fields, and alert workflows fire after an alert is created and routed — not before. To compose a richer title (combining service name, severity, and a summary, for example), construct the title in your sending system before the webhook is sent and map the prepared field as the Title.

What payload shape does Rootly expect?

A JSON object or a flat, UTF-8 form-encoded body with the correct content type. Rootly maps your tool’s existing fields to alert fields during source setup. See Payload Formats for the decoding rules and request example.

Getting Started

Alerts

On-Call

Incident Response

Retrospectives

Status Pages

Communications

Rootly AI

Workflows & Automation

Analytics

Configuration

Integrations

Administration

Resources & Help

Generic Webhook Alert Source

Compatible Alerting Tools

How It Works

Before You Begin

Installation

Payload Formats

Authentication

Mapping Payload Fields

Routing Alerts

Automatically Added Labels

Test the Source

Auto-Resolution

Configure Auto-Resolution

Important Notes

From Alert to Incident

Troubleshooting

Frequently Asked Questions

​Compatible Alerting Tools

​How It Works

​Before You Begin

​Installation

​Payload Formats

​Authentication

​Mapping Payload Fields

​Routing Alerts

​Automatically Added Labels

​Test the Source

​Auto-Resolution

​Configure Auto-Resolution

​Important Notes

​From Alert to Incident

​Troubleshooting

​Frequently Asked Questions

​Related Resources

Compatible Alerting Tools

How It Works

Before You Begin

Installation

Payload Formats

Authentication

Mapping Payload Fields

Routing Alerts

Automatically Added Labels

Test the Source

Auto-Resolution

Configure Auto-Resolution

Important Notes

From Alert to Incident

Troubleshooting

Frequently Asked Questions

Related Resources