Webhook Integrations

Monitoring as Code: Learn more about the Webhook Alert Channel Construct.

Webhooks allow you to POST custom payloads to any endpoint in your own infrastructure or a third party provider. In a nutshell, you can:

Create a custom URL by adding in authentication tokens or other secrets.
Create a custom payload body using any environment variables and specific instance variables per event. Note: that means that if you are attaching the webhook to a Group, you will be able to access Group-level variables, too.
Debug and test the webhook in the editor by sending test messages.

Using Variables

The example above shows a webhook configured to create a Jira ticket on each event. Notice the following:

We use the variable JIRA_INSTANCE_URL in the URL. We previously stored this variable in the environment variables section. Alert-channel configurations accept both environment variables and secrets using the same {{NAME}} syntax.
We use the variable CHECK_ID in the payload. This is one of many event-based variables that will change with each call. See below for the complete list.

In both cases we use the familiar Handlebars templating braces, i.e. {{ }} to insert the variable.

To avoid encoding, you can access your environment variables with triple brackets, i.e. {{{USER_API_KEY}}}

A JSON payload template stays valid JSON when an inserted value contains a double quote or a line break: the value is escaped in the body we send. With {{CHECK_NAME}} a double quote arrives as ", with {{{CHECK_NAME}}} as \"; a line break arrives as \n in both cases.

Using environment variables and secrets in this channel’s configAny literal-secret field in this alert channel — webhook URL, API key, bearer token, service key, etc. — accepts a variable or secret reference using the familiar Handlebars syntax: {{MY_VARIABLE}}.You can also promote a value to a secret directly from the field: type the literal value, click the lock icon next to the input, and choose a name. The value is stored as an encrypted account secret and is never re-displayed in the UI.

You can use the following event-related variables in both URL and payload.

Variable	Description
`AI_ANALYSIS_CLASSIFICATION`	Classification of the failure / error. Available when Rocky AI automation is enabled.
`AI_ANALYSIS_CODE_FIX`	A code fix to resolve the analyzed problem. Available when Rocky AI automation is enabled.
`AI_ANALYSIS_LINK`	Direct link to full AI analysis. Available when Rocky AI automation is enabled.
`AI_ANALYSIS_ROOT_CAUSE`	Description of possible root cause. Available when Rocky AI automation is enabled.
`AI_ANALYSIS_USER_IMPACT`	Description of the user impact. Available when Rocky AI automation is enabled.
`ALERT_TITLE`	Human readable title, e.g. ‘Check “My API check” has failed’
`ALERT_TYPE`	Type of alert, e.g. “ALERT_FAILURE”, “ALERT_RECOVERY”, “ALERT_DEGRADED”, “ALERT_DEGRADED_RECOVERY”. See alert states for all options.
`API_CHECK_RESPONSE_STATUS_CODE`	The response status code, e.g. 200. Only populated for API checks.
`API_CHECK_RESPONSE_STATUS_TEXT`	The response status text, e.g. “OK”. Only populated for API checks.
`CHECK_ERROR_MESSAGE`	The check error message
`CHECK_ID`	The UUID of the check
`CHECK_DESCRIPTION`	The description of the check, if set
`CHECK_NAME`	Full name of the check
`CHECK_RESULT_ID`	The UUID of the result that triggered this message
`CHECK_TYPE`	The check type, e.g. API, BROWSER .
`GROUP_NAME`	The name of the group, if the check belongs to one.
`IS_REMINDER`	Whether this alert is a reminder (`true`) or the initial alert (`false`).
`OTEL_TRACE_ID`	The OpenTelemetry trace ID for the check run. Empty when no trace ID is available.
`OTEL_TRACE_LINK`	URL to view the OpenTelemetry trace for the check run. Empty when no trace is available.
`REGION`	Region code where check ran, e.g. “us-east-1”
`REMINDER_SEQUENCE`	The reminder number (`0` for initial alerts, `1`+ for reminders).
`RESPONSE_TIME`	The reported response time for this result
`RESULT_LINK`	The full link to the check result
`RUN_LOCATION`	The location where the check ran, i.e. “N. California”
`SSL_CHECK_DOMAIN`	The domain of the SSL certificate. For ALERT_SSL only.
`SSL_DAYS_REMAINING`	How many days remain on the SSL certificate. For ALERT_SSL only.
`STARTED_AT`	The ISO timestamp from when this check run started
`TAGS`	An array of tags assigned to the check. Have a look at our Opsgenie example below on how to render this to a JSON array.

Using AI analysis data in alerts

When automatic Rocky AI analysis is enabled, you can include AI-generated root cause and user impact data in your webhook payloads. Use {{#if}} guards so the payload works whether AI analysis data is available or not.

{
  "message": "{{ALERT_TITLE}}",
  "link": "{{RESULT_LINK}}",
  {{#if AI_ANALYSIS_ROOT_CAUSE}}
  "root_cause": "{{AI_ANALYSIS_ROOT_CAUSE}}",
  {{/if}}
  {{#if AI_ANALYSIS_USER_IMPACT}}
  "user_impact": "{{AI_ANALYSIS_USER_IMPACT}}",
  {{/if}}
  {{#if AI_ANALYSIS_LINK}}
  "ai_analysis_link": "{{AI_ANALYSIS_LINK}}",
  {{/if}}
  "classification": "{{AI_ANALYSIS_CLASSIFICATION}}"
}

Handlebars Helpers

Webhook templates support Handlebars built-in helpers, such as if, unless, and each, as well as these Checkly helpers:

Helper	Example	Description
`$UUID`	`{{$UUID}}`	Generates a random UUID v4, such as `9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d`.
`$RANDOM_NUMBER`	`{{$RANDOM_NUMBER}}`	Generates a random integer from 0 through 10,000.
`tagValue`	`{{tagValue TAGS "team" "UNKNOWN"}}`	Returns the value from the first matching `team:value` or `team=value` tag. Returns the optional final argument when no tag matches.
`startsWith`	`{{startsWith value "prefix:"}}`	Returns whether a string starts with the supplied prefix.
`replace`	`{{replace value "old" "new"}}`	Replaces the first matching string.
`split`	`{{split "a,b,c" "," 1}}`	Splits a string and returns the item at the supplied zero-based index.
`year`	`{{year}}` or `{{year 2}}`	Returns the current year with four or two digits.
`date`, `moment`	`{{date "YYYY-MM-DD"}}`	Formats the current date. The two helper names are aliases.

Get a value from a tag

Use tagValue when your tags store key-value metadata. Given these tags:

team:payments
environment=production

This template:

{{tagValue TAGS "team" "UNKNOWN"}}

renders payments. Both : and = separators are supported. If neither team:... nor team=... exists, the template renders the fallback UNKNOWN. If multiple tags match, Checkly returns the first one.

Send a test message from the webhook editor to inspect the rendered request before saving your alert channel.

Format dates and times

The date and moment helpers support Day.js-compatible format tokens. You can format the current time, an absolute date, or relative phrases such as yesterday, 2 days ago, and last week.

{{date "YYYY-MM-DD"}} formats the current date, for example as 2026-07-24.
{{date "2026-07-24" "MMMM DD, YYYY"}} renders July 24, 2026.
{{moment "2 days ago" "YYYY-MM-DD"}} formats the date from two days ago.
{{moment "last week" "X"}} formats last week as a Unix timestamp.

Compare values

Use comparison helpers as blocks or subexpressions where applicable. Available helpers include:

Equality and ordering: eq, is, isnt, gt, gte, lt, lte, and compare.
Boolean logic: and, or, not, neither, isTruthy, and isFalsey.
Value checks: contains, has, and default.
Numeric conditions: ifEven, ifOdd, and ifNth.
Inverse comparisons: unlessEq, unlessGt, unlessGteq, unlessLt, and unlessLteq.

For example:

{
  "message": "Check is {{#eq ALERT_TYPE 'ALERT_FAILURE'}}DOWN{{/eq}} {{#eq ALERT_TYPE 'ALERT_RECOVERY'}}UP{{/eq}}"
}

The above webhook body uses the {{#eq}} helper to execute the logic If the ALERT_TYPE variable equals ‘ALERT_FAILURE’, print ‘DOWN’, if it equals ‘ALERT_RECOVERY’ print ‘UP’ So in the case of a failure event, the body would render to:

{
  "message": "Check is DOWN"
}

Two clear benefits here:

You only need to create one webhook to inform a 3rd party system.
You can translate Checkly terms to your 3rd party tool’s term for the same concept, i.e. the “up status” of a check.

Webhook Secrets

You can validate each webhook we deliver to your endpoint(s). Using the optional webhook secret, you can:

Check if the webhook was sent by Checkly.
Check if the payload was not altered in any way during transmission.

When you create a webhook secret, we use it to sign each webhook: the HTTP header x-checkly-signature contains the HMAC-SHA256 of the raw request body, keyed with your secret and hex-encoded. The signature covers the exact bytes we send, for JSON and plain text bodies alike. On the receiving end, compute the same HMAC over the raw request body, before parsing it, and compare it with the x-checkly-signature header to assert the validity and authenticity of the webhook and its payload. Parsing and re-serializing the body can change its bytes and break the comparison. Have a look at the code examples below on how to use the header and your favourite web framework.

// We store the webhook secret in an environment variable called CHECKLY_WEBHOOK_SECRET
const express = require('express');
const crypto = require('crypto');
const app = express();

function isVerifiedPayload (payload, signature) {
  const secret = process.env.CHECKLY_WEBHOOK_SECRET
  const hmac = crypto.createHmac('sha256', secret)
  const digest = hmac.update(payload).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature))
}

// express.raw() keeps the body as the bytes Checkly sent; parse it only after the signature is verified
app.post('/webhook', express.raw({ type: '*/*' }), (request, response) => {

  const signature = request.headers['x-checkly-signature'];
  const payload = request.body

  if (isVerifiedPayload(payload, signature)) {
    console.log('Signature is valid')
    response.status(200).send();
  } else {
    console.error('Signature does not match')
    response.status(400).send();
  }
});

app.listen(4242, () => console.log('Running on port 4242'))

# We store the webhook secret in an environment variable called CHECKLY_WEBHOOK_SECRET
require 'sinatra'

set :port, 4242

post '/webhook' do
  signature = request.env['HTTP_X_CHECKLY_SIGNATURE']
  payload = request.body.read
  digest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), ENV['CHECKLY_WEBHOOK_SECRET'], payload)

  if Rack::Utils.secure_compare(digest, signature)    
    status 200
    return
  else
    status 400
    return
  end
end

# This example assumes you use Django
import hmac
from hashlib import sha256

from django.conf import settings
from django.http import HttpResponse, HttpResponseBadRequest
from django.views.decorators.csrf import csrf_exempt
from django.utils.encoding import force_bytes
import json

@csrf_exempt
def webhook(request):
    signature = request.META.get('HTTP_X_CHECKLY_SIGNATURE')
    mac = hmac.new(settings.CHECKLY_WEBHOOK_SECRET.encode('utf-8'), msg=request.body, digestmod=sha256)
    print(mac.hexdigest())
    if not hmac.compare_digest(mac.hexdigest(), signature):
        return HttpResponseBadRequest()

    return HttpResponse()

Webhook Retries

Checkly will retry your webhook up to 5 times if the request fails, for example with an HTTP response higher than 399 (such as a 404 or 503), a network error, or no response within 5 seconds. Retries back off exponentially: 10, 20, 40, 80 and 160 seconds, about 5 minutes in total. This means that for checks on a 1 minute schedule, there is a potential overlap between a failure alert and recovery alert. For this reason every webhook we send has a timestamp in the x-checkly-timestamp header. You can use this timestamp on the receiving end to ignore any webhooks that come in “late”.

Webhook Examples

The following examples give an idea how to integrate Checkly with 3rd party alerting and issue tracking systems.

Opsgenie and Jira Service Management

Checkly has no dedicated Jira Service Management (JSM) alert channel. JSM Operations accepts the same alert body as the Opsgenie alerts API, so the webhook below works for both. For JSM, create an API integration in JSM Operations, POST to https://api.atlassian.com/jsm/ops/integration/v2/alerts, and send the integration’s key in the Authorization: GenieKey {{JSM_API_KEY}} header. You can create an Opsgenie alert by POST-ing the following body

{
  "message": "{{ALERT_TITLE}}",
  "description": "{{ALERT_TYPE}} <br>{{STARTED_AT}} ({{RESPONSE_TIME}}ms) <br>{{RESULT_LINK}}",
  "tags": [{{#each TAGS}} "{{this}}" {{#unless @last}},{{/unless}} {{/each}}]
}

to the Opsgenie alerts API endpoint

https://{{OPSGENIE_API_KEY}}@api.opsgenie.com/v2/alerts

Or you can add the Opsgenie API key in the headers, e.g.

Authorization: GenieKey {{OPSGENIE_API_KEY}}

This is an example of a full alert body:

{
  "message": "{{ALERT_TITLE}}",
  "description": "{{ALERT_TYPE}}: {{CHECK_NAME}} <br>{{STARTED_AT}} ({{RESPONSE_TIME}}ms) <br>{{RESULT_LINK}}",
  "responders": [
        {
            "id":"4513b7ea-3b91-438f-b7e4-e3e54af9147c",
            "type":"team"
        }
  ],
  "tags": ["Critical", "Production"],
  "priority":"P1",
  "note": "Location: {{RUN_LOCATION}}"
}

In case you would like different teams to be responsible for different check groups, you could add a CHECK_GROUP_TEAM variable with a different value for each Group, then modify the above snippet with the following:

"responders": [
      {
          "id":"{{CHECK_GROUP_TEAM}}",
          "type":"team"
      }
]

PagerDuty

Given an existing service on your PagerDuty account, create an incident for it by posting the following body

{
  "incident": {
    "type": "incident",
    "title": "{{ALERT_TITLE}}",
    "service": {
      "id": "<YOUR_SERVICE_ID_FROM_PAGERDUTY>",
      "type": "service_reference"
    },
    "body": {
      "type": "incident_body",
      "details": "Check {{CHECK_NAME}} with ID {{CHECK_ID}} has failed from location {{RUN_LOCATION}}. See check result for details: {{RESULT_LINK}}"
    }
  }
}

to https://api.pagerduty.com/incidents. You will need to set the following headers:

Pushover

Send a message using Pushover by posting this body:

{
  "token":"YOUR_SECRET_TOKEN_FROM_PUSHOVER",
  "user":"YOUR_USER_FROM_PUSHOVER",
  "title":"{{ALERT_TITLE}}",
  "html":1,
  "priority":2,
  "retry":30,
  "expire":10800,
  "message":"{{ALERT_TYPE}} <br>{{STARTED_AT}} ({{RESPONSE_TIME}}ms) <br>{{RESULT_LINK}}"
}

Trello

You can create a Trello card using just the URL and no payload:

https://api.trello.com/1/cards?idList=5b28c04aed47522097be8bc4&key={{TRELLO_KEY}}&token={{TRELLO_TOKEN}}&name={{CHECK_NAME}}

SSL alert

You can send your SSL alerts using webhooks. Using the following body:

{
  "message": "{{ALERT_TITLE}}",
  "link":"{{RESULT_LINK}}"
}

Will yield the following output, where we customize the ALERT_TITLE to include the domain and the days remaining till your certificate expires.

{
  "message": "The SSL certificate for api.checklyhq.com will expire in 14 days",
  "link": "http://app-test.checklyhq.com/checks/08437f9c-df8c-45ed-975a-a3f9e24d626d"
}

Twilio

You can configure a webhook to POST to a JavaScript snippet running in a Twilio Function. This code receives the Checkly webhook JSON, then triggers a Twilio “Flow execution”:

//"From" is the sender phone number
//"To" is the receiver phone number
exports.handler = async function (context, event, callback) {
  const { From, To, Event, Link } = event;
  const client = context.getTwilioClient();
  try {
    const execution = await client.studio.flows(FLOW_SID)
      .executions
      .create({ to: To, from: From, parameters: { Event, Link } })
    console.log(`Created execution ${execution.sid}`);
    return callback(null, "OK");
  } catch (error) {
    return callback(error);
  }
};

Jira

A webhook can be used to create a new issue on Jira via the Jira API, for example in the case of a previously passing check that switches to failing state. We will be creating a POST request to {{JIRA_INSTANCE_URL}}/rest/api/3/issue, where the content of your JIRA_INSTANCE_URL environment variable would look something like https://your-jira-instance-name.atlassian.net. The required headers will be:

Authorization: Basic <base64 encoded user_email:api_token_string>
Accept: application/json
Content-Type: application/json

For more details on authenticating with the Jira API, refer to Atlassian’s guide on basic authentication. An example body could look as follows:

{
  "fields": {
    "description": { // your Jira issue description, using Atlassian Document Format (ADF)
      "version": 1,
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "View check result",
              "marks": [
                {
                  "type": "link",
                  "attrs": {
                    "href": "{{RESULT_LINK}}"
                  }
                }
              ]
            }
          ]
        }
      ]
    },
    "issuetype": {
      "id": "10001" // your Jira issue type id
    },
    "labels": [
      "needs_investigation"
    ],
    "priority": { // dynamically set the issue priority, based on the check's tags
      "id": {{#contains TAGS "P1"}} "1"
        {{else}} {{#contains TAGS "P2"}} "2"
        {{else}} {{#contains TAGS "P3"}} "3"
        {{else}} {{#contains TAGS "P4"}} "4"
        {{else}} {{#contains TAGS "P5"}} "5"
        {{else}} "3"
      {{/contains}} {{/contains}} {{/contains}} {{/contains}} {{/contains}}
    },
    "project": {
      "key": "ABC" // your Jira project key
    },
    "summary": "{{ALERT_TITLE}}"
  }
}

For full details on creating issues via the Jira API, see Atlassian’s documentation for this endpoint. You can also use version 2 of the Jira API (i.e. {{JIRA_INSTANCE_URL}}/rest/api/2/issue). The only difference is that version 2 does not support Atlassian Document Format (ADF).

Getting Started

Detect

Communicate

Resolve

AI

Integrations

Using Variables

Using AI analysis data in alerts

Handlebars Helpers

Get a value from a tag

Format dates and times

Compare values

Webhook Secrets

Webhook Retries

Webhook Examples

Opsgenie and Jira Service Management

PagerDuty

Pushover

Trello

SSL alert

Twilio

Jira

​Using Variables

​Using AI analysis data in alerts

​Handlebars Helpers

​Get a value from a tag

​Format dates and times

​Compare values

​Webhook Secrets

​Webhook Retries

​Webhook Examples

​Opsgenie and Jira Service Management

​PagerDuty

​Pushover

​Trello

​SSL alert

​Twilio

​Jira

Using Variables

Using AI analysis data in alerts

Handlebars Helpers

Get a value from a tag

Format dates and times

Compare values

Webhook Secrets

Webhook Retries

Webhook Examples

Opsgenie and Jira Service Management

PagerDuty

Pushover

Trello

SSL alert

Twilio

Jira