GET
/
v1
/
alert-channels
List all alert channels
curl --request GET \
  --url https://api.checklyhq.com/v1/alert-channels \
  --header 'Authorization: <api-key>'
[
  {
    "id": 1,
    "type": "SMS",
    "config": {},
    "subscriptions": [],
    "sendRecovery": true,
    "sendFailure": true,
    "sendDegraded": true,
    "sslExpiry": false,
    "sslExpiryThreshold": 30,
    "autoSubscribe": false,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
]

​
Overview

The List Alert Channels endpoint returns all alert channels configured in your Checkly account. Alert channels define how and where you receive notifications when your checks fail or recover.
Alert channels can be of different types: EMAIL, WEBHOOK, SLACK, SMS, or PHONE. Each type has its own configuration requirements.

​
Response Example

{
  "data": [
    {
      "id": 123,
      "type": "EMAIL",
      "name": "Team Alerts",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:00.000Z",
      "config": {
        "address": "alerts@company.com"
      }
    },
    {
      "id": 124,
      "type": "SLACK",
      "name": "Engineering Channel",
      "createdAt": "2024-01-10T08:15:00.000Z",
      "updatedAt": "2024-01-18T16:20:00.000Z",
      "config": {
        "url": "https://hooks.slack.com/services/...",
        "channel": "#monitoring"
      }
    },
    {
      "id": 125,
      "type": "WEBHOOK",
      "name": "PagerDuty Integration",
      "createdAt": "2024-01-12T12:00:00.000Z",
      "updatedAt": "2024-01-19T09:30:00.000Z",
      "config": {
        "url": "https://events.pagerduty.com/integration/...",
        "method": "POST",
        "headers": [
          {
            "key": "Authorization",
            "value": "Token token=..."
          }
        ]
      }
    }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 3,
    "limit": 10
  }
}

​
Alert Channel Types

Sends notifications via email to specified addresses.Configuration:
  • address (string): Email address to send alerts to
Example:
{
  "type": "EMAIL",
  "name": "Team Email Alerts",
  "config": {
    "address": "team@company.com"
  }
}
Sends notifications to Slack channels via webhooks.Configuration:
  • url (string): Slack webhook URL
  • channel (string, optional): Slack channel name
Example:
{
  "type": "SLACK",
  "name": "Engineering Slack",
  "config": {
    "url": "https://hooks.slack.com/services/...",
    "channel": "#alerts"
  }
}
Sends HTTP requests to custom endpoints.Configuration:
  • url (string): Webhook endpoint URL
  • method (string): HTTP method (GET, POST, PUT, etc.)
  • headers (array, optional): Custom headers
  • queryParameters (array, optional): Query parameters
Example:
{
  "type": "WEBHOOK",
  "name": "Custom Integration",
  "config": {
    "url": "https://api.example.com/alerts",
    "method": "POST",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer token123"
      }
    ]
  }
}
Sends text message notifications to phone numbers.Configuration:
  • number (string): Phone number in international format
  • name (string): Display name for the SMS alert
Example:
{
  "type": "SMS",
  "name": "On-call SMS",
  "config": {
    "number": "+1234567890",
    "name": "Emergency Alerts"
  }
}
Makes phone calls for critical alerts.Configuration:
  • number (string): Phone number in international format
  • name (string): Display name for the phone alert
Example:
{
  "type": "PHONE",
  "name": "Critical Phone Alerts",
  "config": {
    "number": "+1234567890",
    "name": "Emergency Line"
  }
}

​
Use Cases

Team Notifications

Set up email or Slack alerts to keep your team informed about check failures

Escalation Chains

Configure SMS and phone alerts for critical checks that require immediate attention

Integration Webhooks

Connect to external systems like PagerDuty, OpsGenie, or custom incident management tools

Multi-Channel Strategy

Combine multiple alert types for comprehensive coverage based on severity and time of day

​
Additional Examples

curl -X GET "https://api.checklyhq.com/v1/alert-channels" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000"
Alert channels are shared across your entire account. When you create a check, you can subscribe it to one or more alert channels to receive notifications when that specific check fails or recovers.

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

Query Parameters

​
limit
integer
default:10

Limit the number of results

Required range: 1 <= x <= 100
​
page
number
default:1

Page number

Response

Successful

​
id
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.

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
​
autoSubscribe
boolean
default:false

Automatically subscribe newly created checks to this alert channel.

​
created_at
string<date-time>
​
updated_at
string<date-time>