Create Alert Channel

Overview

Create a new alert channel to define how and where you receive notifications when your checks fail or recover. Each alert channel type requires specific configuration parameters.

Creating alert channels may be subject to plan limits. You’ll receive a 402 Payment Required response if you exceed your plan’s alert channel limit.

Request Examples

{
  "type": "EMAIL",
  "name": "Team Email Alerts",
  "config": {
    "address": "team@company.com"
  }
}

Response Example

{
  "id": 126,
  "type": "SLACK",
  "name": "Engineering Slack",
  "createdAt": "2024-01-25T10:30:00.000Z",
  "updatedAt": "2024-01-25T10:30:00.000Z",
  "config": {
    "url": "https://hooks.slack.com/services/T1234567/B1234567/abcdef123456",
    "channel": "#monitoring"
  }
}

Configuration by Type

EMAIL Configuration

Required Fields:

address (string): Valid email address

Example:

{
  "type": "EMAIL",
  "name": "Development Team",
  "config": {
    "address": "dev-team@company.com"
  }
}

SLACK Configuration

Required Fields:

url (string): Slack webhook URL

Optional Fields:

channel (string): Target Slack channel (e.g., “#alerts”)

Getting a Slack Webhook URL:

Go to your Slack workspace settings
Navigate to “Incoming Webhooks”
Create a new webhook for your desired channel
Copy the generated webhook URL

Example:

{
  "type": "SLACK",
  "name": "Production Alerts",
  "config": {
    "url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
    "channel": "#production-alerts"
  }
}

WEBHOOK Configuration

Required Fields:

url (string): Target webhook endpoint
method (string): HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD)

Optional Fields:

headers (array): Custom HTTP headers
queryParameters (array): URL query parameters

Header/Parameter Format:

{
  "key": "header-name",
  "value": "header-value"
}

Example:

{
  "type": "WEBHOOK",
  "name": "Custom Integration",
  "config": {
    "url": "https://api.mycompany.com/webhooks/alerts",
    "method": "POST",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer your-api-token"
      }
    ]
  }
}

SMS Configuration

Required Fields:

number (string): Phone number in international format (E.164)
name (string): Display name for the SMS alert

Phone Number Format:

Must start with + followed by country code
Example: +1234567890 for US numbers

Example:

{
  "type": "SMS",
  "name": "Emergency SMS",
  "config": {
    "number": "+1555123456",
    "name": "On-call Engineer"
  }
}

PHONE Configuration

Required Fields:

number (string): Phone number in international format (E.164)
name (string): Display name for the phone alert

Example:

{
  "type": "PHONE",
  "name": "Critical Outage Line",
  "config": {
    "number": "+1555987654",
    "name": "Emergency Contact"
  }
}

Code Examples

curl -X POST "https://api.checklyhq.com/v1/alert-channels" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "EMAIL",
    "name": "Team Alerts",
    "config": {
      "address": "alerts@company.com"
    }
  }'

Best Practices

Naming Conventions

Use descriptive names that indicate:

The team or purpose
The urgency level
The communication channel type

Examples:

“Engineering Team - Critical Alerts”
“Marketing Dashboard - Email Notifications”
“On-call Engineer - SMS Only”

Webhook Security

Always use HTTPS endpoints
Include authentication headers
Consider IP whitelisting on your webhook endpoint
Validate webhook payloads in your receiving application

Phone Number Format

Always use E.164 international format
Include country code with + prefix
Test phone numbers before using in production
Consider time zones for phone alerts

Slack Integration

Use dedicated channels for monitoring alerts
Set up appropriate channel permissions
Consider using Slack’s threading feature for related alerts
Test webhook URLs before saving

After creating an alert channel, you can subscribe it to specific checks or check groups to receive notifications when those monitors fail or recover. Alert channels can be reused across multiple checks.

Authorizations

Authorization

string

header

required

The Checkly Public API uses API keys to authenticate requests. You can get the API Key here.

Your API key is like a password: keep it secure!

Authentication to the API is performed using the Bearer auth method in the Authorization header and using the account ID.

For example, set Authorization header while using cURL:

curl -H "Authorization: Bearer [apiKey]" "X-Checkly-Account: [accountId]"

Headers

x-checkly-account

string

Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

Body

application/json

type

enum<string>

required

Available options:

EMAIL,

SLACK,

WEBHOOK,

SMS,

PAGERDUTY,

OPSGENIE,

CALL

Example:

"SMS"

config

object

required

subscriptions

object[]

All checks subscribed to this channel.

Show child attributes

Example:

[]

sendRecovery

boolean

sendFailure

boolean

sendDegraded

boolean

sslExpiry

boolean

default:false

Determines if an alert should be sent for expiring SSL certificates.

sslExpiryThreshold

integer

default:30

At what moment in time to start alerting on SSL certificates.

Required range: 1 <= x <= 30

Automatically subscribe newly created checks to this alert channel.

Response

Created

number

required

Example:

1

type

enum<string>

required

Available options:

EMAIL,

SLACK,

WEBHOOK,

SMS,

PAGERDUTY,

OPSGENIE,

CALL

Example:

"SMS"

config

object

required

The configuration details for this alert channel. These can be very different based on the type of the channel.

subscriptions

object[]

All checks subscribed to this channel.

Show child attributes

Example:

[]

sendRecovery

boolean

sendFailure

boolean

sendDegraded

boolean

sslExpiry

boolean

default:false

Determines if an alert should be sent for expiring SSL certificates.

sslExpiryThreshold

integer

default:30

At what moment in time to start alerting on SSL certificates.

Required range: 1 <= x <= 30

Automatically subscribe newly created checks to this alert channel.

created_at

string<date-time>

updated_at

string<date-time>

Platform

Detect

Communicate

Resolve

Overview

Request Examples

Response Example

Configuration by Type

Code Examples

Best Practices

Authorizations

Headers

Body

Response

Platform

Detect

Communicate

Resolve

​Overview

​Request Examples

​Response Example

​Configuration by Type

​Code Examples

​Best Practices

Authorizations

Headers

Body

Response

Overview

Request Examples

Response Example

Configuration by Type

Code Examples

Best Practices