Skip to main content

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.

​
Overview

Outgoing webhooks let you push Rootly events to any system that accepts HTTP POST requests — a custom internal tool, a data pipeline, an audit log, or a third-party service that does not have a native Rootly integration. Each webhook endpoint you configure receives a JSON payload for the event types you subscribe it to. Rootly signs every delivery so your server can verify the payload came from Rootly.

​
Create a Webhook Endpoint

1

Navigate to Webhooks

Go to Settings → Webhooks and click New Webhook.
2

Name and URL

Give the endpoint a descriptive name and enter the destination URL. The URL must be publicly reachable and accept HTTPS POST requests.
​
Name
string
required
A label for this endpoint, unique within your team.
​
URL
string
required
The HTTPS endpoint that will receive event payloads.
3

Select event types

Choose which events this endpoint should receive. If you leave the event types list empty, the endpoint will receive all events.See Event Types below for the full list.
4

Save and copy the secret

Click Save. Rootly generates a signing secret for this endpoint automatically. Copy it now — it is only shown once. You will use it to verify incoming payloads on your server.
The signing secret cannot be retrieved after you leave this page. If you lose it, you can regenerate it from the endpoint’s edit form, which will invalidate the old secret immediately.

​
Event Types

Subscribe an endpoint to one or more event types. An empty subscription list means the endpoint receives all events.

​
Incidents

EventWhen it fires
incident.createdA new incident is opened
incident.updatedAny field on the incident changes
incident.in_triageIncident moves to In Triage status
incident.mitigatedIncident is marked as mitigated
incident.resolvedIncident is resolved
incident.cancelledIncident is cancelled
incident.deletedIncident is deleted

​
Scheduled Incidents

EventWhen it fires
incident.scheduled.createdA scheduled incident is created
incident.scheduled.updatedA scheduled incident is updated
incident.scheduled.in_progressA scheduled incident becomes active
incident.scheduled.completedA scheduled incident completes
incident.scheduled.deletedA scheduled incident is deleted

​
Retrospectives

EventWhen it fires
incident_post_mortem.createdA retrospective is created
incident_post_mortem.updatedA retrospective is updated
incident_post_mortem.publishedA retrospective is published
incident_post_mortem.deletedA retrospective is deleted

​
Status Page Events

EventWhen it fires
incident_status_page_event.createdA status page event is created
incident_status_page_event.updatedA status page event is updated
incident_status_page_event.deletedA status page event is deleted

​
Timeline Events

EventWhen it fires
incident_event.createdA timeline event is added to an incident
incident_event.updatedA timeline event is updated
incident_event.deletedA timeline event is deleted

​
Alerts and Pulses

EventWhen it fires
alert.createdAn alert is created in Rootly
pulse.createdA pulse is created

​
Workflows

EventWhen it fires
genius_workflow_run.queuedA workflow run is queued
genius_workflow_run.startedA workflow run begins executing
genius_workflow_run.completedA workflow run completes successfully
genius_workflow_run.failedA workflow run fails
genius_workflow_run.canceledA workflow run is cancelled
For payload examples for the most common event types, see Event Payloads.

​
Delivery and Retries

Each event triggers a separate HTTP POST to every matching enabled endpoint. Rootly expects a 2xx response within 10 seconds. If the delivery fails or times out, Rootly retries automatically on the following schedule:
AttemptDelay after previous failure
1st retry15 seconds
2nd retry1 minute
3rd retry5 minutes
After three failed retries the delivery is abandoned. You can inspect delivery history — including response status codes and response bodies — from the endpoint detail page in Settings → Webhooks.
Retries use the same payload as the original attempt. If your endpoint processed the event before returning an error, implement idempotency using the event ID in the payload to avoid duplicate processing.

​
Verifying Webhook Signatures

Every delivery includes an X-Rootly-Signature header containing a timestamp and an HMAC-SHA256 signature. Use this to confirm the payload originated from Rootly. 
X-Rootly-Signature: t=1492774588,v1=6657a869e8ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
To verify:
  1. Extract the timestamp (t=) and signature (v1=) from the header.
  2. Concatenate the timestamp with the raw request body.
  3. Compute an HMAC-SHA256 digest of that string using your endpoint’s signing secret.
  4. Compare the result to the v1 value. If they match, the payload is authentic.
require 'openssl'
require 'rack'

header = request.headers['X-Rootly-Signature']
parts = header.split(',')
timestamp = parts[0].split('t=').last
signature = parts[1].split('v1=').last
secret = 'your_webhook_secret'

expected = OpenSSL::HMAC.hexdigest('SHA256', secret, timestamp + request.body.read)
is_valid = Rack::Utils.secure_compare(expected, signature)
To prevent replay attacks, also check that the timestamp in the header is within a few minutes of the current time before accepting the payload.

​
Manage Endpoints

From Settings → Webhooks you can:
  • Enable or disable an endpoint without deleting it — disabled endpoints receive no deliveries.
  • Edit the name, URL, or event subscriptions at any time.
  • View delivery history for each endpoint, including the HTTP status code and response body for each attempt.
  • Delete an endpoint to permanently stop deliveries to that URL.

​
Troubleshooting

Check that the endpoint is enabled in Settings → Webhooks. Also verify that the event types you expect are included in the endpoint’s subscription, or that the subscription list is empty (which receives all events). If the URL requires authentication headers or is behind an IP allowlist, those must be handled at the receiving server — Rootly sends only the X-Rootly-Signature header alongside the standard Content-Type: application/json header.
Rootly waits up to 10 seconds for a response. If your endpoint takes longer to process, return a 200 immediately and handle the payload asynchronously. Rootly will retry failed deliveries up to three times before abandoning the delivery.
You can regenerate the signing secret from the endpoint’s edit form in Settings → Webhooks. Regenerating immediately invalidates the old secret, so update your server-side verification logic before regenerating.
Use a tool like ngrok or localtunnel to expose a local port over a public HTTPS URL, then register that URL as a webhook endpoint in Rootly. Trigger a test event by creating or updating an incident, and inspect the delivery in the endpoint detail view.