WebhookAlertChannel Construct

Learn how to configure webhook alert channels with the Checkly CLI.

For general information about alerting, see our docs on webhook alerts and alerting with Checkly.

Sends alert notifications as HTTP requests to any URL. This is the most flexible alert channel type, allowing integration with any service that accepts webhooks.

You can customize the payload with our Handlebars-style variables and helpers.

Basic Example

import { WebhookAlertChannel } from "checkly/constructs"

const webhookChannel = new WebhookAlertChannel("webhook-channel-1", {
  name: "Basic Webhook",
  method: "POST",
  url: new URL("https://api.example.com/webhooks/checkly"),
  template: JSON.stringify({
    message: "Check {{ALERT_TITLE}} is {{ALERT_TYPE}}",
    timestamp: "{{STARTED_AT}}",
  }),
})

If you need to reference existing alert channels that were created outside of your CLI project, use fromId().

Configuration

Webhook Alert Channel

Configure webhook-specific settings:

Parameter	Type	Required	Default	Description
url	URL	✅	-	Target URL for the webhook request
method	string	✅	-	HTTP method: GET | POST | PUT | PATCH | HEAD | DELETE
name	string	❌	-	Friendly name for the webhook channel
template	string	❌	-	Request body template with Handlebars-style variables
headers	array	❌	[]	Array of { key, value } objects for HTTP headers
queryParameters	array	❌	[]	Array of { key, value } objects for query parameters
webhookSecret	string	❌	''	Value to use as secret for the webhook

General Alert Channel

Configure common alert channel properties:

Property	Type	Required	Default	Description
sendRecovery	boolean	❌	true	Send notifications when checks recover
sendFailure	boolean	❌	true	Send notifications when checks fail
sendDegraded	boolean	❌	false	Send notifications when checks degrade
sslExpiry	boolean	❌	false	Send notifications for SSL certificate expiry
sslExpiryThreshold	number	❌	30	Days before SSL expiry to send notification

Webhook Alert Channel Options

url · URL · required

Target URL for the webhook request.

new WebhookAlertChannel('webhook-channel-1', {
  name: 'Pushover webhook',
  method: 'POST',
  url: new URL('https://api.pushover.net/1/messages.json'),
})

method · string · required

The HTTP method, either GET, POST, PUT, PATCH, HEAD or DELETE.

name · string

Friendly name for the webhook channel.

template · string

The request body template, usually JSON. You can use Handlebars-style template variables to add custom data to the template.

new WebhookAlertChannel('webhook-channel-1', {
  name: 'Pushover webhook',
  method: 'POST',
  url: new URL('https://api.pushover.net/1/messages.json'),
  template: `{
    "token":"FILL_IN_YOUR_SECRET_TOKEN_FROM_PUSHOVER",
    "user":"FILL_IN_YOUR_USER_FROM_PUSHOVER",
    "title":"{{ALERT_TITLE}}",
    "html":1,
    "priority":2,
    "retry":30,
    "expire":10800,
    "message":"{{ALERT_TYPE}} {{STARTED_AT}} ({{RESPONSE_TIME}}ms) {{RESULT_LINK}}"
  }`
})

headers · array

An array of { key, value } objects to define HTTP headers.

new WebhookAlertChannel('webhook-channel-1', {
  name: 'Pushover webhook',
  method: 'POST',
  url: new URL('https://api.pushover.net/1/messages.json'),
  headers: [{ key: 'X-My-Header', value: '123' }],
})

queryParameters · array

An array of { key, value } objects to define query parameters.

new WebhookAlertChannel('webhook-channel-1', {
  name: 'Pushover webhook',
  method: 'POST',
  url: new URL('https://api.pushover.net/1/messages.json'),
  queryParameters: [{ key: 'my-param', value: '123' }],
})

webhookSecret · string

Secret token that you can use to validate the authenticity of the webhook and its payload. Learn more about webhook secrets.

General Alert Channel Options

These options are valid for all alert channels types.

sendRecovery · boolean

Whether to send notifications when checks recover from a failed or degraded state. Default value is true.

sendFailure · boolean

Whether to send notifications when checks fail. Default value is true.

sendDegraded · boolean

Whether to send notifications when checks become degraded. Default value is false.

sslExpiry · boolean

Whether to send notifications when a SSL/TLS certificate is about to expire. Default value is false.

new EmailAlertChannel("email-channel-1", {
  address: "[e-mail]",
  sslExpiry: true,
  sslExpiryThreshold: 30, // Alert 30 days before expiry
})

Learn more about SSL alerts.

sslExpiryThreshold · number

Number of days before the SSL/TLS certificate expiry date to send notifications. Only relevant when sslExpiry is enabled. Default value is 30.

new EmailAlertChannel("email-channel-1", {
  address: "[e-mail]",
  sslExpiry: true,
  sslExpiryThreshold: 30, // Alert 30 days before expiry
})

Learn more about SSL alerts.