Skip to main content

​
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

Required Fields:
  • address (string): Valid email address
Example:
{
  "type": "EMAIL",
  "name": "Development Team",
  "config": {
    "address": "dev-team@company.com"
  }
}
Required Fields:
  • url (string): Slack webhook URL
Optional Fields:
  • channel (string): Target Slack channel (e.g., “#alerts”)
Getting a Slack Webhook URL:
  1. Go to your Slack workspace settings
  2. Navigate to “Incoming Webhooks”
  3. Create a new webhook for your desired channel
  4. Copy the generated webhook URL
Example:
{
  "type": "SLACK",
  "name": "Production Alerts",
  "config": {
    "url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
    "channel": "#production-alerts"
  }
}
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"
      }
    ]
  }
}
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"
  }
}
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

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”
  • Always use HTTPS endpoints
  • Include authentication headers
  • Consider IP whitelisting on your webhook endpoint
  • Validate webhook payloads in your receiving application
  • Always use E.164 international format
  • Include country code with + prefix
  • Test phone numbers before using in production
  • Consider time zones for phone alerts
  • 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.