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.

Page On-Call

Trigger escalation policies the moment a Checkly check fails, paging the right responder in seconds.

Auto-Create Incidents

Turn a degraded check into a full Rootly incident with custom fields, workflows, and Slack channels.

Auto-Resolve On Recovery

Map Checkly’s recovery event to rootly_alert_status and the alert closes itself when the check comes back.

Per-Check Routing

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.
• 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.

1. Open Alerts → Sources

   In the Rootly dashboard, navigate to Alerts → Sources and click New alert source.

2. Choose Checkly

   Select Checkly from the list of available sources and give the source a descriptive name — for example, Checkly — Production Synthetics.

3. Set The Default Routing Target (Optional)

   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.

4. Copy The Webhook URL And Secret

   Rootly generates a unique webhook URL and a per-source secret. Copy both — they go into Checkly next.

   Without a default routing target:

   https://webhooks.rootly.com/webhooks/incoming/checkly_webhooks
   

   With a default routing target baked into the URL:

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

---

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.

1. Create A New Webhook Alert Channel

   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.

2. Set The Request Details

   Configure the request:

   Method · string · required

   POST

   URL · string · required

   The webhook URL you copied from Rootly.

   Custom Header · key/value · required

   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.

3. Paste The Payload Template

   Use the JSON template below. Checkly substitutes the {{ }} Handlebars variables with values from the failing check at send time.

   Basic Alert

   Standard template — alert lands in Rootly and routes based on the source’s default target.

   {
     "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}}"
   }
   

   Per-Check Routing

   Add a rootly object to route this specific check to a different service, team, or escalation policy.

   {
     "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.

   Recovery (Auto-Resolve)

   Use this template on a second Checkly alert channel scoped to recovery events. The rootly_alert_status field closes the matching alert in Rootly.

   {
     "check_id": "{{CHECK_ID}}",
     "check_name": "{{CHECK_NAME}}",
     "alert_title": "{{ALERT_TITLE}}",
     "started_at": "{{STARTED_AT}}",
     "rootly_alert_status": "resolved"
   }
   
4. Save And Attach To Checks

   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.

check_name · string · required

The name of the Checkly check that fired. Joined with alert_title using " - " to form the Rootly alert’s summary.

alert_title · string · required

The descriptive title Checkly attached to the alert. Combined with check_name for the alert summary.

check_id · string · required

Stable identifier for the check. Rootly uses this as the External Identifier to match recovery events back to the original alert for auto-resolution.

started_at · ISO 8601 datetime

When the check first failed. Populates the alert’s started-at timestamp.

link · URL

Direct link back to the failing check in the Checkly dashboard. Preserved on the alert record for responders to jump straight to the source.

rootly.notification_target · object

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).

rootly_alert_status · string

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.

By URL (One Target)

Set a default routing target when you create the alert source. Rootly bakes it into the webhook URL:

https://webhooks.rootly.com/webhooks/incoming/checkly_webhooks/notify/Service/<service-id>

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.

By Payload (Per Check)

Leave the default target empty on the Rootly source. In each Checkly alert channel’s payload template, add a rootly object naming the target:

"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 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 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.

1. Send A Test Webhook From Checkly

   Open the alert channel you created and click Send test webhook. Checkly POSTs a sample payload to the Rootly URL.

2. Confirm The Alert Appears In Rootly

   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.

3. Optional — Trigger A Real Failure

   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

Rootly returns 401 Unauthorized

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.

The webhook returns 200 but no alert appears in Rootly

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

Recovery events don't resolve the original alert

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".

Alerts route to the wrong team or service

URL-based routing takes precedence over payload-based routing. If the webhook URL ends with /notify/<type>/<id>, 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 retried the webhook five times

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

Do I need to use the Generic Webhook source for Checkly?

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.

Can one Checkly account feed multiple Rootly alert sources?

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.

Does the integration support HMAC signatures?

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.

What if I want to page on-call directly instead of just creating an alert?

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.

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

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

Alert Routing

Configure routes that send alerts from this source to the right responders based on severity, region, or any custom field.

Alert Workflows

Auto-create incidents, post Slack notifications, run runbooks, and chain follow-up actions from Checkly alerts.

Alert Fields

Extract custom fields from the Checkly payload (severity, region, deployment) for richer routing and reporting.

Schedule Permissions

Confirm which Rootly roles can create and edit this alert source.