> ## 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. # Checkly > Connect Checkly to Rootly to turn synthetic check failures and API monitoring alerts into routed, actionable incidents and on-call pages. ## Overview Checkly's synthetic checks and API monitors fire webhook alerts the moment something fails. Wire those webhooks at Rootly and every failure becomes a normalized alert that can page on-call, route to the right service, or auto-create an incident through alert workflows. Recovery events from Checkly close the same alert automatically, so your timeline stays clean. Checkly has first-class support as a dedicated alert source in Rootly — you don't need the Generic Webhook source. The integration ships with vendor-specific payload parsing, pre-mapped fields, a `secret`-header authentication path, and a guided setup wizard in the Rootly dashboard. Trigger escalation policies the moment a Checkly check fails, paging the right responder in seconds. Turn a degraded check into a full Rootly incident with custom fields, workflows, and Slack channels. Map Checkly's recovery event to `rootly_alert_status` and the alert closes itself when the check comes back. Send API checks to one team, browser checks to another, all from a single Checkly alert channel. *** ## Before You Begin **You'll need access to both sides of the connection.** * **In Rootly** — the **On-Call Admin** or **On-Call User** role so you can create alert sources. See [Schedule Permissions](/on-call/schedules#permissions-access). * **In Checkly** — permission to add and configure alert channels under **Alert Settings**. A clear routing plan helps too: decide whether every alert from this source should land on the same service or team, or whether routing varies per check. *** ## Add the Alert Source in Rootly The Rootly side hands you a webhook URL and a `secret` value — paste those into Checkly in the next section. In the Rootly dashboard, navigate to **Alerts → Sources** and click **New alert source**. Select **Checkly** from the list of available sources and give the source a descriptive name — for example, `Checkly — Production Synthetics`. If every alert from this source should always route to the same service, team, or escalation policy, set the target on the source configuration page. Leave it blank if you want routing to come from each check's payload instead — covered under [Routing Alerts](#routing-alerts). Rootly generates a unique webhook URL and a per-source `secret`. Copy both — they go into Checkly next. Without a default routing target: ```text theme={null} https://webhooks.rootly.com/webhooks/incoming/checkly_webhooks ``` With a default routing target baked into the URL: ```text theme={null} https://webhooks.rootly.com/webhooks/incoming/checkly_webhooks/notify// ``` *** ## Configure the Webhook in Checkly Create a webhook alert channel in Checkly, point it at the Rootly URL, and use the payload template Rootly expects. In Checkly, navigate to **Alert Settings → Alert Channels** and click **Add channel**. Choose **Webhook**. For the latest Checkly UI specifics, refer to [Checkly's webhook alert channel documentation](https://www.checklyhq.com/docs/alerting-and-retries/webhooks/). Configure the request: `POST` The webhook URL you copied from Rootly. Key: `secret` — Value: the secret you copied from Rootly. Rootly's Checkly source authenticates the request using the custom `secret` header, not Bearer Token or HMAC. Without it, Rootly returns `401 Unauthorized` and the alert is dropped. Use the JSON template below. Checkly substitutes the `{{ }}` Handlebars variables with values from the failing check at send time. Standard template — alert lands in Rootly and routes based on the source's default target. ```json theme={null} { "alert_type": "{{ALERT_TYPE}}", "check_id": "{{CHECK_ID}}", "check_result_id": "{{CHECK_RESULT_ID}}", "check_name": "{{CHECK_NAME}}", "alert_title": "{{ALERT_TITLE}}", "started_at": "{{STARTED_AT}}", "link": "{{RESULT_LINK}}" } ``` Add a `rootly` object to route this specific check to a different service, team, or escalation policy. ```json theme={null} { "alert_type": "{{ALERT_TYPE}}", "check_id": "{{CHECK_ID}}", "check_name": "{{CHECK_NAME}}", "alert_title": "{{ALERT_TITLE}}", "started_at": "{{STARTED_AT}}", "link": "{{RESULT_LINK}}", "rootly": { "notification_target": { "type": "Service", "id": "8c4a5e91-1b2d-4c3e-9f6a-7d8b2c5e9a01" } } } ``` Valid `type` values are the Rootly resource class names: `Service`, `Group`, or `EscalationPolicy`. Use this template on a second Checkly alert channel scoped to recovery events. The `rootly_alert_status` field closes the matching alert in Rootly. ```json theme={null} { "check_id": "{{CHECK_ID}}", "check_name": "{{CHECK_NAME}}", "alert_title": "{{ALERT_TITLE}}", "started_at": "{{STARTED_AT}}", "rootly_alert_status": "resolved" } ``` Save the alert channel, then attach it to the checks (or check groups) you want forwarded to Rootly. New failures on those checks POST to the Rootly webhook URL within seconds. *** ## Payload Reference Rootly's Checkly source parses these fields from each incoming webhook. The full raw payload is also preserved on the alert record, so any extra fields Checkly sends remain accessible to alert routes, workflows, and field mappings. The name of the Checkly check that fired. Joined with `alert_title` using `" - "` to form the Rootly alert's summary. The descriptive title Checkly attached to the alert. Combined with `check_name` for the alert summary. Stable identifier for the check. Rootly uses this as the **External Identifier** to match recovery events back to the original alert for auto-resolution. When the check first failed. Populates the alert's started-at timestamp. Direct link back to the failing check in the Checkly dashboard. Preserved on the alert record for responders to jump straight to the source. Optional. Sets the routing target for this specific alert. Used only when the alert source does **not** have a default URL-based target — if a URL target is configured on the source, it takes precedence and the payload target is ignored. Expects `type` (`Service`, `Group`, or `EscalationPolicy`) and `id` (the Rootly resource's internal ID). Optional. Sets the alert state directly. Use `resolved` on recovery channels so Checkly's "check is back" event closes the original Rootly alert. *** ## Routing Alerts Two ways to point a Checkly alert at the right responder. URL-based routing takes precedence when both are set on the same request. Set a default routing target when you create the alert source. Rootly bakes it into the webhook URL: ```text theme={null} https://webhooks.rootly.com/webhooks/incoming/checkly_webhooks/notify/Service/ ``` Every alert from this Checkly channel routes to that target — no payload-level routing needed. **Best when**: a single Checkly account corresponds to one Rootly team or service. Leave the default target empty on the Rootly source. In each Checkly alert channel's payload template, add a `rootly` object naming the target: ```json theme={null} "rootly": { "notification_target": { "type": "Service", "id": "8c4a5e91-1b2d-4c3e-9f6a-7d8b2c5e9a01" } } ``` Valid `type` values are the Rootly resource class names: `Service`, `Group`, or `EscalationPolicy`. The `id` is the Rootly resource's internal ID — open the resource in Rootly and copy it from the edit page. Names and slugs aren't accepted. **Best when**: different checks need to page different teams. You can hardcode targets per channel, or use Checkly's per-check variables to switch them dynamically. *** ## Auto-Resolution Checkly fires a recovery event whenever a failing check comes back to passing. Rootly closes the original alert automatically when the recovery payload includes `"rootly_alert_status": "resolved"`. The cleanest pattern is **two separate Checkly alert channels** scoped to different alert events: * **Failure channel** — uses the **Basic Alert** payload from the [Configure step](#configure-the-webhook-in-checkly) above, unchanged. No `rootly_alert_status` field needed; Rootly defaults to a triggered state when one isn't present. * **Recovery channel** — uses the **Recovery (Auto-Resolve)** template, which hardcodes `"rootly_alert_status": "resolved"`. Rootly matches the two events using the **External Identifier** (`check_id`) and transitions the same alert from triggered to resolved. See [Alert Statuses](/alerts/alert-statuses) for the full lifecycle. *** ## Test the Integration After saving the alert channel in Checkly, run a test to confirm the connection works end-to-end. Open the alert channel you created and click **Send test webhook**. Checkly POSTs a sample payload to the Rootly URL. Open the Checkly alert source in Rootly. The test alert should appear in the source's recent activity within a few seconds. Click into it to verify the title, started-at timestamp, and link populated correctly. For full end-to-end verification, deliberately fail a check (point an API check at a 500-returning endpoint, for example) and confirm the alert reaches Rootly with the correct routing target and triggers the workflow you expect. A successful test alert in Rootly means the webhook URL, the `secret` header, and the payload template are all wired correctly. You're ready to attach the channel to production checks. *** ## Troubleshooting The `secret` header is missing or doesn't match the value shown on the Rootly source configuration. Re-copy the secret from Rootly, paste it as a custom header in the Checkly alert channel (header key: `secret`, value: the secret string), and re-send a test. Rootly processes webhooks asynchronously, so check again after a few seconds. If the alert still doesn't appear: * Confirm the routing target referenced in the URL or payload exists and isn't archived * Inspect the source's recent activity in Rootly to verify the payload was received * Verify `check_name` and `alert_title` aren't empty in the payload template Either the recovery payload has a different `check_id` than the failure event, or the `rootly_alert_status` field isn't set to `resolved` (case-sensitive). Confirm both events come from the same Checkly check and that the recovery channel's template hardcodes `"rootly_alert_status": "resolved"`. URL-based routing takes precedence over payload-based routing. If the webhook URL ends with `/notify//`, that target wins regardless of the JSON body. Either remove the URL target and rely on payload routing, or update the URL target to the correct destination. Checkly retries up to five times with 20-second backoff on any HTTP response above 399. If Rootly returned `401`, check the `secret` header. If Rootly returned `500`, contact Rootly support with the timestamps so they can correlate against server logs. *** ## Frequently Asked Questions No. Rootly ships a dedicated Checkly alert source with vendor-specific payload parsing, pre-mapped fields, and the `secret`-header authentication shown above. Use it instead of the Generic Webhook source for a cleaner setup and built-in field mappings. Yes. Create a separate Checkly alert channel for each Rootly source you want to feed — each with its own webhook URL and secret — and attach each channel to the relevant checks. Useful when different check groups need to route to different Rootly teams. Rootly's Checkly source authenticates via the `secret` custom header, not HMAC. Checkly's optional `x-checkly-signature` SHA-256 signature isn't required and isn't validated. Set the source's default routing target (or the payload's `rootly.notification_target`) to an **Escalation Policy**. Rootly triggers the escalation as soon as the alert is created, paging the on-call responder per the policy's steps. Adjust the payload template in Checkly's alert channel. The `check_name` and `alert_title` Handlebars variables can be combined with static text — for example, `"alert_title": "[{{SEVERITY}}] {{CHECK_NAME}} failing"`. Rootly stores whatever string you produce as the alert summary. *** ## Next Steps Configure routes that send alerts from this source to the right responders based on severity, region, or any custom field. Auto-create incidents, post Slack notifications, run runbooks, and chain follow-up actions from Checkly alerts. Extract custom fields from the Checkly payload (severity, region, deployment) for richer routing and reporting. Confirm which Rootly roles can create and edit this alert source.