> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Generic Webhook Alert Source
> Ingest alerts from any monitoring, observability, or security tool into Rootly via webhook — works with any system that can POST JSON to a URL.
The **Generic Webhook Alert Source** lets Rootly ingest alerts from any tool that can fire HTTP webhooks. If your monitoring, observability, security, or data-quality platform can send a POST with a JSON body, Rootly can turn that event into an alert, route it to the right responder, and trigger 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
If a tool can send an HTTP POST with a JSON body, it works with Rootly. The Generic Webhook Alert Source is the standard way to wire up alerts from:
* **Application performance & error tracking** — BugSnag, AppOptics, Coralogix
* **Infrastructure & log monitoring** — Sumo Logic, Elastic, Chronosphere, Nagios, PRTG
* **Uptime & synthetic monitoring** — Pingdom, StatusCake, 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](/integrations/overview), 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:
1. **Authenticates the request** using the Bearer Token configured for the source.
2. **Parses the JSON body** and extracts the fields you mapped — title, description, identifier, state, routing target.
3. **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.
4. **Routes the alert** to the target you specified, either from the URL or from the payload itself.
5. **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.
***
## 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 on the [Installation](/integrations/generic-webhook-alert-source/installation) page.
***
## Mapping Payload Fields
Rootly doesn't require a specific JSON shape. You map fields from your sending tool's payload to Rootly's alert fields during source creation.
A typical payload from a monitoring tool:
```json theme={null}
{
"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](/integrations/generic-webhook-alert-source/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](/integrations/generic-webhook-alert-source/installation) guide for the field-mapping UI walkthrough.
***
## Routing Alerts
There are two ways to tell Rootly where an alert should go. You can mix both across sources, but a single source typically uses one or the other.
Include the target type and ID directly in the webhook URL Rootly generates:
```
POST https://webhooks.rootly.com/webhooks/incoming/generic_webhooks/notify//
```
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, no payload mapping required for the target.
Send the target type and ID in the JSON body and let Rootly extract them via field mappings:
```json theme={null}
{
"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.
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 and you want that metadata to drive routing.
Common target types: `service`, `group` (or `team`), `escalationPolicy`.
***
## Auto-Resolution
When your sending tool fires a recovery or "cleared" event, Rootly can transition the original alert to resolved automatically. The match happens on the External Identifier, and the trigger is an exact-match value in the State field (typically `resolved`, `recovered`, or `ok`).
Configure auto-resolution after you've set up the source and its field mappings. The dedicated [Auto-Resolution](/integrations/generic-webhook-alert-source/auto-resolution) page covers the matching rules, payload requirements, and how to define the resolved-state value.
***
## 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](/workflows/alert-workflows) decide what the alert *means* and what should happen next.
***
## Installation
The full step-by-step setup — creating the source, copying the endpoint URL, configuring authentication, mapping payload fields, configuring routing, and testing the integration — lives on the dedicated [Installation](/integrations/generic-webhook-alert-source/installation) page.
***
## Troubleshooting
The most common cause is a missing or mismatched Bearer token. Confirm:
* The `Authorization: Bearer ` 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
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
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.
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.
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 the [Auto-Resolution](/integrations/generic-webhook-alert-source/auto-resolution) page for the matching rules.
Switch from URL-based routing to payload-based routing. Map the target type and target ID fields from the incoming JSON so the routing decision lives in the event itself.
***
## Frequently Asked Questions
No. If your tool can send an HTTP POST with a JSON body, the Generic Webhook Alert Source can ingest its alerts. Native integrations are nicer when they exist because they ship with vendor-specific field mappings and reduce setup time, but they're not required.
Alerts are signals — discrete events from your monitoring stack. Incidents are coordinated response — the war room, the timeline, the postmortem. One incident may be informed by many alerts. The webhook source creates alerts; [alert workflows](/workflows/alert-workflows) decide when an alert should escalate to an incident.
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.
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.
Both work. Rootly accepts the Bearer secret either as the `Authorization: Bearer ` header or as a `secret` query string parameter on the webhook URL.
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.
Any valid JSON. Rootly doesn't require a specific schema — instead you map your tool's existing fields to Rootly's alert fields during source setup. Most monitoring tools work out of the box; you just point them at the webhook URL and configure the mapping.
***
## Related Pages
Step-by-step setup with code samples, payload mapping, routing, and testing.
Match recovery events to the original alert and resolve automatically.
Turn alerts into incidents, page on-call, post notifications, and run custom automation.