WebhookAlertChannel Construct

Learn more about Webhook alerts in the webhook alert documentation.

Use Webhook Alert Channels to send HTTP requests to any URL when checks fail or recover. This is the most flexible alert channel type, allowing integration with any service that accepts HTTP webhooks.

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}}",
  }),
})

Configuration

Webhook Alert Channel
General 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

Webhook Alert Channel Options

url

URL

required

Target URL for the webhook request. This is where Checkly will send the HTTP request when alerts are triggered.Usage:

new WebhookAlertChannel("webhook-channel", {
  name: "API Integration",
  method: "POST",
  url: new URL("https://api.example.com/webhooks/checkly"),
})

Examples:

const directWebhook = new WebhookAlertChannel("direct-webhook", {
  name: "Direct API",
  method: "POST",
  url: new URL("https://api.example.com/alerts/webhooks"),
})

Use cases: Service integration, webhook endpoints, secure URL storage, API communication.

method

string

required

HTTP method for the webhook request. Supported methods: GET, POST, PUT, PATCH, HEAD, DELETE.Usage:

new WebhookAlertChannel("webhook-channel", {
  name: "API Integration",
  method: "POST", // Most common for webhooks
  url: new URL("https://api.example.com/webhooks"),
})

Examples:

const postWebhook = new WebhookAlertChannel("post-webhook", {
  name: "POST Webhook",
  method: "POST",
  url: new URL("https://api.example.com/webhooks"),
  template: JSON.stringify({
    message: "{{ALERT_TITLE}}",
    status: "{{ALERT_TYPE}}",
  }),
})

Use cases: RESTful API integration, service-specific requirements.

name

string

Friendly name for the webhook channel to identify it in your Checkly dashboard.Usage:

new WebhookAlertChannel("webhook-channel", {
  name: "Custom API Integration",
  method: "POST",
  url: new URL("https://api.example.com/webhooks"),
})

Examples:

const pushoverWebhook = new WebhookAlertChannel("pushover-webhook", {
  name: "Pushover Notifications",
  method: "POST",
  url: new URL("https://api.pushover.net/1/messages.json"),
})

const discordWebhook = new WebhookAlertChannel("discord-webhook", {
  name: "Discord Notifications",
  method: "POST",
  url: new URL(
    "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
  ),
})

Use cases: Integration identification, operational clarity.

template

string

Request body template (commonly JSON) with Handlebars-style variables that are replaced with alert data.Usage:

new WebhookAlertChannel("template-webhook", {
  name: "Templated Webhook",
  method: "POST",
  url: new URL("https://api.example.com/webhooks"),
  template: JSON.stringify({
    message: "Check {{CHECK_NAME}} is {{ALERT_TYPE}}",
    timestamp: "{{STARTED_AT}}",
  }),
})

Examples:

const basicWebhook = new WebhookAlertChannel("basic-webhook", {
  name: "Basic Template",
  method: "POST",
  url: new URL("https://api.example.com/alerts"),
  template: JSON.stringify({
    title: "{{ALERT_TITLE}}",
    type: "{{ALERT_TYPE}}",
    check: "{{CHECK_NAME}}",
    location: "{{RUN_LOCATION}}",
  }),
})

Use cases: Custom message formatting, service-specific payloads, data transformation.

headers

array

Array of HTTP headers to include in the webhook request. Each header is an object with key and value properties.Usage:

new WebhookAlertChannel("headers-webhook", {
  name: "Headers Webhook",
  method: "POST",
  url: new URL("https://api.example.com/webhooks"),
  headers: [
    { key: "Authorization", value: "Bearer {{API_TOKEN}}" },
    { key: "Content-Type", value: "application/json" },
  ],
})

Examples:

const authWebhook = new WebhookAlertChannel("auth-webhook", {
  name: "Authenticated Webhook",
  method: "POST",
  url: new URL("https://api.example.com/secure"),
  headers: [
    { key: "Authorization", value: "Bearer {{API_SECRET}}" },
    { key: "X-API-Key", value: "{{API_KEY}}" },
    { key: "Content-Type", value: "application/json" },
  ],
})

Use cases: Authentication, content type specification, custom metadata, service requirements.

queryParameters

array

Array of query parameters to include in the webhook URL. Each parameter is an object with key and value properties.Usage:

new WebhookAlertChannel("query-webhook", {
  name: "Query Webhook",
  method: "GET",
  url: new URL("https://api.example.com/notify"),
  queryParameters: [
    { key: "source", value: "checkly" },
    { key: "alert_type", value: "{{ALERT_TYPE}}" },
  ],
})

Examples:

const getWebhook = new WebhookAlertChannel("get-params-webhook", {
  name: "GET with Parameters",
  method: "GET",
  url: new URL("https://api.example.com/notify"),
  queryParameters: [
    { key: "alert_type", value: "{{ALERT_TYPE}}" },
    { key: "check_name", value: "{{CHECK_NAME}}" },
    { key: "location", value: "{{RUN_LOCATION}}" },
    { key: "response_time", value: "{{RESPONSE_TIME}}" },
  ],
})

Use cases: API requirements, metadata passing, GET request data, service routing.

General Alert Channel Options

sendRecovery

boolean

Whether to send webhook requests when checks recover from failure or degraded state.Usage:

new WebhookAlertChannel("recovery-webhook", {
  name: "Recovery Notifications",
  method: "POST",
  url: new URL(process.env.WEBHOOK_URL!),
  sendRecovery: true, // Send webhooks for recovery notifications
})

Examples:

const opsWebhook = new WebhookAlertChannel("ops-webhook", {
  name: "Operations Webhook",
  method: "POST",
  url: new URL(process.env.OPS_WEBHOOK_URL!),
  sendRecovery: true, // Get notified when issues are resolved
  sendFailure: true,
})

Use cases: Recovery confirmation, operational awareness, noise reduction.

sendFailure

boolean

Whether to send webhook requests when checks fail.Usage:

new WebhookAlertChannel("failure-webhook", {
  name: "Failure Notifications",
  method: "POST",
  url: new URL(process.env.WEBHOOK_URL!),
  sendFailure: true, // Send webhooks for failure notifications
})

Examples:

const criticalWebhook = new WebhookAlertChannel("critical-webhook", {
  name: "Critical Alerts",
  method: "POST",
  url: new URL(process.env.CRITICAL_WEBHOOK_URL!),
  sendFailure: true, // Critical failures
  sendRecovery: true,
  sendDegraded: false, // No degraded alerts
})

Use cases: Incident response, failure monitoring, operational alerting.

sendDegraded

boolean

Whether to send webhook requests when API checks degrade (performance thresholds exceeded but not failed).Usage:

new WebhookAlertChannel("performance-webhook", {
  name: "Performance Monitoring",
  method: "POST",
  url: new URL(process.env.PERFORMANCE_WEBHOOK_URL!),
  sendDegraded: true, // Send webhooks for degraded performance
})

Examples:

import { ApiCheck, WebhookAlertChannel } from "checkly/constructs"

const performanceWebhook = new WebhookAlertChannel("performance-webhook", {
  name: "Performance Team",
  method: "POST",
  url: new URL(process.env.PERFORMANCE_WEBHOOK_URL!),
  sendRecovery: true,
  sendFailure: true,
  sendDegraded: true, // Alert on degraded performance
})

new ApiCheck("performance-check", {
  name: "API Performance Check",
  maxResponseTime: 5000,
  degradedResponseTime: 2000, // Triggers degrade alerts
  alertChannels: [performanceWebhook],
  request: {
    method: "GET",
    url: "https://api.example.com/slow-endpoint",
  },
})

Use cases: Performance monitoring, early warning systems, SLA tracking.

sslExpiry

boolean

Whether to send webhook requests for SSL certificate expiry warnings.Usage:

new WebhookAlertChannel("security-webhook", {
  name: "Security Team",
  method: "POST",
  url: new URL(process.env.SECURITY_WEBHOOK_URL!),
  sslExpiry: true,
  sslExpiryThreshold: 30, // Alert 30 days before expiry
})

Examples:

import { ApiCheck, WebhookAlertChannel } from "checkly/constructs"

const securityWebhook = new WebhookAlertChannel("security-webhook", {
  name: "Security Team Alerts",
  method: "POST",
  url: new URL(process.env.SECURITY_WEBHOOK_URL!),
  sendRecovery: false,
  sendFailure: true,
  sslExpiry: true,
  sslExpiryThreshold: 14, // Alert 14 days before expiry
})

new ApiCheck("ssl-cert-check", {
  name: "SSL Certificate Check",
  alertChannels: [securityWebhook],
  request: {
    method: "GET",
    url: "https://secure.example.com",
  },
})

Use cases: Certificate management, security compliance, proactive maintenance.

sslExpiryThreshold

number

Number of days before SSL certificate expiry to send webhook requests. Only relevant when sslExpiry is enabled.Usage:

new WebhookAlertChannel("ssl-monitoring", {
  name: "SSL Monitoring",
  method: "POST",
  url: new URL(process.env.DEVOPS_WEBHOOK_URL!),
  sslExpiry: true,
  sslExpiryThreshold: 30, // Alert 30 days before expiry
})

Examples:

// Give plenty of time for certificate renewal
new WebhookAlertChannel("ssl-conservative", {
  name: "SSL Conservative Warning",
  method: "POST",
  url: new URL(process.env.DEVOPS_WEBHOOK_URL!),
  sslExpiry: true,
  sslExpiryThreshold: 60, // 60 days notice
})

Use cases: Certificate renewal planning, compliance management, operational scheduling.

Template Configuration

Learn more about using environment and predefined variables in your webhook template in the webhook documentation.

Examples

const pushoverWebhook = new WebhookAlertChannel("pushover-webhook", {
  name: "Pushover Notifications",
  method: "POST",
  url: new URL("https://api.pushover.net/1/messages.json"),
  template: JSON.stringify({
    token: "{{PUSHOVER_APP_TOKEN}}",
    user: "{{PUSHOVER_USER_KEY}}",
    title: "{{ALERT_TITLE}}",
    message:
      "{{CHECK_NAME}} is {{ALERT_TYPE}} ({{RESPONSE_TIME}}ms) - {{RESULT_LINK}}",
    html: 1,
    priority: 2,
    retry: 30,
    expire: 10800,
  }),
})

Environment Variables in Templates

Use environment variables in your webhook templates for sensitive data:

const webhookChannel = new WebhookAlertChannel("secure-webhook", {
  name: "Secure Webhook",
  method: "POST",
  url: new URL("https://api.example.com/webhooks"),
  headers: [{ key: "Authorization", value: "Bearer {{API_TOKEN}}" }],
  template: JSON.stringify({
    api_key: "{{SECRET_API_KEY}}",
    alert: "{{ALERT_TITLE}}",
  }),
})

Security: Be careful with sensitive data in webhook templates. Use environment variables for API tokens and secrets.

Getting Started

DETECT

COMMUNICATE

Project & Configuration

WebhookAlertChannel Construct

Configuration

Webhook Alert Channel Options

General Alert Channel Options

Template Configuration

Examples

Environment Variables in Templates

Getting Started

DETECT

COMMUNICATE

Project & Configuration

​Configuration

​Webhook Alert Channel Options

​General Alert Channel Options

​Template Configuration

​Examples

​Environment Variables in Templates

Configuration

Webhook Alert Channel Options

General Alert Channel Options

Template Configuration

Examples

Environment Variables in Templates