diff --git a/constructs/alert-channel.mdx b/constructs/alert-channel.mdx new file mode 100644 index 00000000..39eed3ce --- /dev/null +++ b/constructs/alert-channel.mdx @@ -0,0 +1,46 @@ +--- +title: 'Alert Channel Overview' +description: 'Learn how to configure alert channels with the Checkly CLI.' +sidebarTitle: 'Overview' +--- + +import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; + +Alert channels let you get alert notifications when a check or monitor fails. [Learn more about alerting in our docs](/communicate/alerts/overview/). + +## Common properties + +All alert channels share a set of common properties to define when / how they should alert derived from the abstract class +`AlertChannel`. + + + +Alert channels are assigned to checks, monitors, and groups by instantiating a class and adding the resulting object to the +`alertChannels` array. + +To assign alert channels to `CheckGroupV2` constructs, you'll also need to set the [`alertEscalationPolicy`](/constructs/check-group-v2#param-alert-escalation-policy) to enable the group alerting override. + +## Using `fromId()` to reference an existing channel + +You can reference an existing alert channel in your Checkly account using the `fromId()` method on any `AlertChannel` +class. When your CLI project is responsible for creating and managing alert channels, it integrates seamlessly with Checkly's deployment control mechanisms. This ensures that any changes made are thoroughly validated. + +For users with multiple Checkly CLI projects: + +- Alert channels can be set up through the Checkly UI or any other method, ensuring they remain intact and unaffected by individual CLI project operations. + +For users managing a single Checkly CLI project: + +- The entire process of creating and subscribing to alert channels can be handled within that single project. This is made possible because the project references the logical ID of the alert channel, rather than an ID generated post-deployment. + + +If you attempt to deploy a project that references alert channels which have been removed or are no longer valid, the deployment process will not proceed. This feature helps maintain the integrity and reliability of your monitoring and alerting setup. + + +```ts +export const emailChannel = EmailAlertChannel.fromId(20) +``` + +You can obtain the ID for your alert channel either from the [Checkly web UI](https://app.checklyhq.com/accounts/alerts/settings) or by utilizing our [REST API](/api-reference/alert-channels/list-all-alert-channels/). + +![email channel id](/images/docs/images/cli/constructs_email_id@2x.jpg) \ No newline at end of file diff --git a/constructs/email-alert-channel.mdx b/constructs/email-alert-channel.mdx index ba9f35c0..dc1d3ffe 100644 --- a/constructs/email-alert-channel.mdx +++ b/constructs/email-alert-channel.mdx @@ -1,13 +1,14 @@ --- title: 'EmailAlertChannel Construct' description: 'Learn how to configure email alert channels with the Checkly CLI.' -sidebarTitle: 'Email Alert Channel' +sidebarTitle: 'Email' --- import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; +import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx'; -Learn more about Email alerts in [the email alert documentation](/integrations/alerts/email). +For general information about alerting, see our docs on [email alerts](/integrations/alerts/email) and [alerting with Checkly](/communicate/alerts/overview/). Use Email Alert Channels to send email notifications when checks fail or recover. @@ -37,6 +38,10 @@ const emailChannel = new EmailAlertChannel("ops-email-channel", { + + If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel). + + ## Configuration @@ -59,276 +64,9 @@ Configure Email-specific settings: ### Email Alert Channel Options -Email address to send notifications to. Each EmailAlertChannel supports only one email address. - -**Usage:** - -```ts highlight={2} -new EmailAlertChannel('team-email', { - address: 'dev-team@acme.com' -}) -``` - -**Examples:** - - - -```ts Team Notifications -const teamEmail = new EmailAlertChannel("team-email", { - address: "dev-team@acme.com", -}) - -new ApiCheck("api-health-check", { - name: "API Health Check", - alertChannels: [teamEmail], - request: { - method: "GET", - url: "https://api.acme.com/health", - }, -}) -``` - -```ts Individual Developer -const developerEmail = new EmailAlertChannel("developer-email", { - address: "john.doe@acme.com", -}) - -new ApiCheck("personal-project-check", { - name: "Personal Project Check", - alertChannels: [developerEmail], - request: { - method: "GET", - url: "https://johnspersonalapi.com/status", - }, -}) -``` - - - -**Use cases**: Team notifications, individual alerts, distribution lists, role-based alerting. +Email address to send notifications to. Each `EmailAlertChannel` supports only one email address, do not use multiple addresses separated by a comma. ### General Alert Channel Options - -Whether to send notifications when checks recover from failure or degraded state. - -**Usage:** - -```ts highlight={3} -new EmailAlertChannel("recovery-email", { - address: "ops@acme.com", - sendRecovery: true, // Send recovery notifications -}) -``` - -**Examples:** - - - -```ts Recovery Notifications -const opsEmail = new EmailAlertChannel("ops-email", { - address: "ops@acme.com", - sendRecovery: true, // Get notified when issues are resolved - sendFailure: true, -}) -``` - -```ts Failure Only -const alertsEmail = new EmailAlertChannel("alerts-only", { - address: "alerts@acme.com", - sendRecovery: false, // Only failures, no recovery notifications - sendFailure: true, -}) -``` - - - -**Use cases**: Recovery confirmation, operational awareness, noise reduction. - - - -Whether to send notifications when checks fail. - -**Usage:** - -```ts highlight={3} -new EmailAlertChannel("failure-email", { - address: "oncall@acme.com", - sendFailure: true, // Send failure notifications -}) -``` - -**Examples:** - - - -```ts Failures Only -const criticalEmail = new EmailAlertChannel("critical-email", { - address: "oncall@acme.com", - sendFailure: true, - sendRecovery: false, - sendDegraded: false, -}) -``` - -```ts All Notifications -const comprehensiveEmail = new EmailAlertChannel("all-notifications", { - address: "monitoring@acme.com", - sendFailure: true, - sendRecovery: true, - sendDegraded: true, -}) -``` - - - -**Use cases**: Incident response, failure monitoring, operational alerting. - - - - -Whether to send notifications when API checks degrade (performance thresholds exceeded but not failed). - -**Usage:** - -```ts highlight={3} -new EmailAlertChannel("performance-email", { - address: "performance-team@acme.com", - sendDegraded: true, // Send degraded performance notifications -}) -``` - -**Use cases**: Performance monitoring, early warning systems, SLA tracking. - - - -Whether to send notifications for SSL certificate expiry warnings. - -**Usage:** - -```ts highlight={3} -new EmailAlertChannel("security-email", { - address: "security@acme.com", - sslExpiry: true, - sslExpiryThreshold: 30, // Alert 30 days before expiry -}) -``` - -**Use cases**: Certificate management, security compliance, proactive maintenance. - - - -Number of days before SSL certificate expiry to send notifications. Only relevant when `sslExpiry` is enabled. - -**Usage:** - -```ts highlight={4} -new EmailAlertChannel("ssl-monitoring", { - address: "devops@acme.com", - sslExpiry: true, - sslExpiryThreshold: 30, // Alert 30 days before expiry -}) -``` - -**Use cases**: Certificate renewal planning, compliance management, operational scheduling. - - -## Examples - - - -```ts Multiple Recipients -// Create separate channels for different recipients -const devEmail = new EmailAlertChannel("dev-email", { - address: "dev@acme.com", - sendDegraded: true, -}) - -const opsEmail = new EmailAlertChannel("ops-email", { - address: "ops@acme.com", - sendFailure: true, - sendRecovery: true, -}) - -const managerEmail = new EmailAlertChannel("manager-email", { - address: "manager@acme.com", - sendFailure: true, - sendRecovery: false, -}) - -new ApiCheck("important-service", { - name: "Important Service Check", - alertChannels: [devEmail, opsEmail, managerEmail], - request: { - method: "GET", - url: "https://api.acme.com/important", - }, -}) -``` - -```ts Comprehensive Setup -// Full configuration example -const comprehensiveEmail = new EmailAlertChannel("comprehensive-alerts", { - address: "monitoring@acme.com", - sendRecovery: true, // Know when issues are resolved - sendFailure: true, // Critical for incident response - sendDegraded: true, // Early warning for performance issues - sslExpiry: true, // Certificate management - sslExpiryThreshold: 30, // One month notice -}) - -new ApiCheck("comprehensive-monitoring", { - name: "Comprehensive API Monitoring", - maxResponseTime: 10000, - degradedResponseTime: 5000, - alertChannels: [comprehensiveEmail], - request: { - method: "GET", - url: "https://api.acme.com/comprehensive", - }, -}) -``` - - - - -**Single Email Address**: EmailAlertChannel only accepts one email address. For multiple recipients, create separate EmailAlertChannel instances or use distribution lists. - - - -**Email Delivery**: Email notifications may be subject to spam filters or delivery delays. For critical alerts, consider combining email with other notification methods like SMS or Slack. - - -## Reference an alert channel by ID - -If your Checkly account includes alert channels that are not controlled via Checkly constructs, find the email channel ID in the Checkly web UI or via the API and set it using `EmailAlertChannel.fromId()`. - - - - 1. Go to [Alert Channels](https://app.checklyhq.com/alerts/) in your Checkly dashboard - 2. Find your email channel and note the ID in the URL or channel details - - - - ```bash - curl -H "Authorization: Bearer YOUR_API_KEY" \ - -H "X-Checkly-Account: YOUR_ACCOUNT_ID" \ - https://api.checklyhq.com/v1/alert-channels/ - ``` - - - -```ts Using Existing Channel -// Reference an existing email channel by ID -const existingEmailChannel = EmailAlertChannel.fromId(123) - -new ApiCheck("existing-channel-check", { - name: "Check with Existing Channel", - alertChannels: [existingEmailChannel], - request: { - method: "GET", - url: "https://api.acme.com/endpoint", - }, -}) -``` + diff --git a/constructs/incidentio-alert-channel.mdx b/constructs/incidentio-alert-channel.mdx new file mode 100644 index 00000000..5ec7d875 --- /dev/null +++ b/constructs/incidentio-alert-channel.mdx @@ -0,0 +1,128 @@ +--- +title: 'IncidentioAlertChannel Construct' +description: 'Learn how to configure Incident.io alert channels with the Checkly CLI.' +sidebarTitle: 'Incident.io' +--- + +import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; +import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx'; + + + +For general information about alerting, see our docs on [the Incident.io integration](/integrations/incident-management/incidentio) and [alerting with Checkly](/communicate/alerts/overview/). + + +Triggers and resolves alerts in Incident.io. + + + +```ts Basic Example +import { IncidentioAlertChannel } from 'checkly/constructs' + +const incidentioChannel = new IncidentioAlertChannel('incidentio-channel-1', { + name: 'ACME alerts', + url: 'https://api.incident.io/v2/alert_events/checkly/xxxxx', + apiKey: 'xxxxx45afe73' +}) +``` + +```ts Advanced Example +import { IncidentioAlertChannel } from 'checkly/constructs' + +const incidentioChannel = new IncidentioAlertChannel('incidentio-channel-1', { + name: 'ACME alerts', + url: 'https://api.incident.io/v2/alert_events/checkly/xxxxx', + apiKey: 'xxxxx45afe73', + sendRecovery: true, + sendFailure: true, + sendDegraded: true, + sslExpiry: true, + sslExpiryThreshold: 30, +}) +``` + + + + + If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel). + + +## Configuration + + + + +Configure Incident.io-specific settings: + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `name` | `string` | ✅ | - | Friendly name to recognise the integration | +| `url` | `string` | ✅ | - | The target URL created by installing the Checkly integration in Incident.io | +| `apiKey` | `string` | ✅ | - | The API key created by installing the Checkly integration in Incident.io | +| `payload` | `string` | ❌ | Includes a title, description, deduplication key, and more | The payload sent to the target URL when an alert is triggered | + + + + + + + + + +### Incident.io Alert Channel Options + + +Friendly name to recognise the integration. + + + +The target URL created by installing the Checkly integration in Incident.io. + + + +The API key created by installing the Checkly integration in Incident.io. + + + +The payload sent to the target URL when an alert is triggered. If this is not specified, we'll send a default payload with a basic title, description, etc. + +We have [handlebar helpers and variables](/integrations/alerts/webhooks/#using-variables) available for building custom payloads. + +Here's an example payload, using the default one that we provide: + +```ts highlight={5-26} +new IncidentioAlertChannel('incidentio-channel-1', { + name: 'ACME alerts', + url: 'https://api.incident.io/v2/alert_events/checkly/xxxxx', + apiKey: 'xxxxx45afe73', + payload: ` + { + "title": "{{ALERT_TITLE}}", + "description": "{{ALERT_TITLE}} at {{STARTED_AT}} in {{RUN_LOCATION}} {{RESPONSE_TIME}}ms\\n\\n{{#if AI_ANALYSIS_CLASSIFICATION}}# AI Analysis\\n\\n{{AI_ANALYSIS_CLASSIFICATION}}\\n\\n{{{AI_ANALYSIS_ROOT_CAUSE}}}\\nRead full analysis: {{AI_ANALYSIS_LINK}}{{/if}}", + "deduplication_key": "{{CHECK_ID}}", + "metadata": { + {{#if AI_ANALYSIS_CLASSIFICATION}} + "ai_analysis_classification": "{{AI_ANALYSIS_CLASSIFICATION}}", + "ai_analysis_root_cause": "{{{AI_ANALYSIS_ROOT_CAUSE}}}", + "ai_analysis_link": "{{AI_ANALYSIS_LINK}}", + {{/if}} + "alertType": "{{ALERT_TYPE}}", + "check_result_id": "{{CHECK_RESULT_ID}}", + "resultLink": "{{RESULT_LINK}}" + }, + {{#contains ALERT_TYPE "RECOVERY"}} + "status": "resolved" + {{else}} + "status": "firing" + {{/contains}} + } + ` +}) +``` + + +### General Alert Channel Options + + + + diff --git a/constructs/msteams-alert-channel.mdx b/constructs/msteams-alert-channel.mdx index cfa1c884..5512276e 100644 --- a/constructs/msteams-alert-channel.mdx +++ b/constructs/msteams-alert-channel.mdx @@ -1,44 +1,166 @@ --- title: 'MSTeamsAlertChannel Construct' description: 'Learn how to configure Microsoft Teams alert channels with the Checkly CLI.' -sidebarTitle: 'MS Teams Alert Channel' +sidebarTitle: 'Microsoft Teams' --- import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; +import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx'; -Learn more about Microsoft Teams alerts in [the Microsoft Teams Alerts documentation](/integrations/alerts/msteams). +For general information about alerting, see our docs on [Microsoft Teams alerts](/integrations/alerts/msteams) and [alerting with Checkly](/communicate/alerts/overview/). -Use Microsoft Teams Alert Channels to send notifications to Microsoft Teams channels when checks fail or recover. Teams alerts help keep your team informed and enable quick collaboration on issues. +Sends alert notifications to a Microsoft Teams channel via a Workflow webhook. ```ts Basic Example -import { MSTeamsAlertChannel } from "checkly/constructs" +import { MSTeamsAlertChannel } from 'checkly/constructs' -const teamsChannel = new MSTeamsAlertChannel("teams-channel-1", { - name: "Dev Team Alerts", - url: "https://prod-24.westus.logic.azure.com:443/workflows/xxxxx", +const msTeamsAlertChannel = new MSTeamsAlertChannel('msteams-channel-01', { + name: 'ACME alerts', + url: 'https://prod-24.westus.logic.azure.com:443/workflows/xxxxx', }) ``` ```ts Advanced Example -import { MSTeamsAlertChannel } from "checkly/constructs" +import { MSTeamsAlertChannel } from 'checkly/constructs' -const teamsChannel = new MSTeamsAlertChannel("advanced-teams-channel", { - name: "Production Monitoring Alerts", - url: "https://prod-24.westus.logic.azure.com:443/workflows/xxxxx", +const msTeamsAlertChannel = new MSTeamsAlertChannel('msteams-channel-01', { + name: 'ACME alerts', + url: 'https://prod-24.westus.logic.azure.com:443/workflows/xxxxx', sendRecovery: true, sendFailure: true, sendDegraded: true, sslExpiry: true, sslExpiryThreshold: 14, + payload: `{ + "type":"message", + "attachments":[ + { + "contentType":"application/vnd.microsoft.card.adaptive", + "contentUrl":null, + "content":{ + "$schema":"http://adaptivecards.io/schemas/adaptive-card.json", + "type":"AdaptiveCard", + "version":"1.2", + "body":[ + { + "type": "Container", + "items": [ + { + "type": "TextBlock", + "text": "{{ALERT_TITLE}}", + "weight": "Bolder", + "size": "Large", + "style": "heading" + }, + {{#if AI_ANALYSIS_CLASSIFICATION}} + { + "type": "TextBlock", + "text": "AI analysis", + "weight": "Bolder", + "size": "Default", + "style": "heading" + }, + { + "type": "ColumnSet", + "columns": [ + { + "type": "Column", + "width": "stretch", + "items": [ + { + "type": "TextBlock", + "text": "{{AI_ANALYSIS_CLASSIFICATION}}", + "weight": "Bolder", + "wrap": true + }, + { + "type": "TextBlock", + "text": "{{AI_ANALYSIS_ROOT_CAUSE}}", + "wrap": true + } + ] + } + ] + }, + { + "type": "ActionSet", + "actions": [ + { + "type": "Action.OpenUrl", + "title": "Read full analysis", + "url": "{{AI_ANALYSIS_LINK}}", + "style": "positive", + "iconUrl": "icon:Sparkle" + } + ] + }, + {{/if}} + { + "type": "ColumnSet", + "columns": [ + { + "type": "Column", + "width": "stretch", + "items": [ + { + "type": "TextBlock", + "text": "Response time: {{RESPONSE_TIME}}ms", + "wrap": true + }, + { + "type": "TextBlock", + "text": "Location: {{RUN_LOCATION}}", + "wrap": true + }, + { + "type": "TextBlock", + "text": "Timestamp: {{STARTED_AT}}", + "wrap": true + }, + {{#if GROUP_NAME}} + { + "type": "TextBlock", + "text": "Group: {{GROUP_NAME}}", + "wrap": true + }, + {{/if}} + { + "type": "TextBlock", + "text": "Tags: {{#each TAGS}} {{this}} {{#unless @last}},{{/unless}} {{/each}}", + "wrap": true + } + ] + } + ] + } + ] + } + ], + "actions":[ + { + "type":"Action.OpenUrl", + "title":"View in Checkly", + "url":"{{RESULT_LINK}}", + "style": "positive" + } + ] + } + } + ] +}` }) ``` + + If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel). + + ## Configuration @@ -48,7 +170,7 @@ Configure Microsoft Teams-specific settings: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| -| `url` | `string` | ✅ | - | Microsoft Teams webhook URL created by the Workflow | +| `url` | `string` | ✅ | - | The target URL created by creating a Workflow in Microsoft Teams | | `name` | `string` | ❌ | - | Friendly name to recognize the integration | | `payload` | `string` | ❌ | - | Custom payload for the alert message | @@ -61,158 +183,148 @@ Configure Microsoft Teams-specific settings: -## Examples - - - - ```ts - import { MSTeamsAlertChannel, ApiCheck } from "checkly/constructs" - - const devTeamsAlert = new MSTeamsAlertChannel("dev-team-alerts", { - name: "Development Team Alerts", - url: "https://prod-24.westus.logic.azure.com:443/workflows/dev-team-webhook", - }) - - new ApiCheck("dev-api-check", { - name: "Development API Health", - alertChannels: [devTeamsAlert], - tags: ["development", "api"], - request: { - method: "GET", - url: "https://dev-api.example.com/health", - }, - }) - ``` - - - - ```ts - import { ApiCheck, MSTeamsAlertChannel } from "checkly/constructs" - - const opsTeamsAlert = new MSTeamsAlertChannel("ops-team-alerts", { - name: "Operations Team Alerts", - url: "https://prod-24.westus.logic.azure.com:443/workflows/ops-team-webhook", - sendRecovery: true, - sendFailure: true, - sendDegraded: true, // Ops team wants to know about degraded performance - }) - - new ApiCheck("infrastructure-check", { - name: "Infrastructure Health Check", - alertChannels: [opsTeamsAlert], - maxResponseTime: 5000, - degradedResponseTime: 2000, - tags: ["infrastructure", "operations"], - request: { - method: "GET", - url: "https://infrastructure.example.com/health", - }, - }) - ``` - - - - ```ts - import { ApiCheck, MSTeamsAlertChannel } from "checkly/constructs" - - const devTeams = new MSTeamsAlertChannel("dev-teams", { - name: "Development Team", - url: "https://prod-24.westus.logic.azure.com:443/workflows/dev-webhook", - }) - - const opsTeams = new MSTeamsAlertChannel("ops-teams", { - name: "Operations Team", - url: "https://prod-24.westus.logic.azure.com:443/workflows/ops-webhook", - }) - - const businessTeams = new MSTeamsAlertChannel("business-teams", { - name: "Business Team", - url: "https://prod-24.westus.logic.azure.com:443/workflows/business-webhook", - sendFailure: true, - sendRecovery: true, - sendDegraded: false, // Business team only needs to know about failures - }) - - new ApiCheck("multi-team-check", { - name: "Cross-Team Critical Service", - alertChannels: [devTeams, opsTeams, businessTeams], - tags: ["cross-team", "critical"], - request: { - method: "GET", - url: "https://critical-service.example.com/health", - }, - }) - ``` - - - - ```ts - import { ApiCheck, MSTeamsAlertChannel } from "checkly/constructs" - - const prodTeams = new MSTeamsAlertChannel("prod-teams", { - name: "Production Alerts", - url: "https://prod-24.westus.logic.azure.com:443/workflows/prod-webhook", - }) - - const stagingTeams = new MSTeamsAlertChannel("staging-teams", { - name: "Staging Environment Alerts", - url: "https://prod-24.westus.logic.azure.com:443/workflows/staging-webhook", - sendDegraded: true, // More tolerant for staging - }) - - // Production monitoring - new ApiCheck("prod-api-check", { - name: "Production API", - alertChannels: [prodTeams], - tags: ["production"], - request: { - method: "GET", - url: "https://api.example.com/health", - }, - }) - - // Staging monitoring - new ApiCheck("staging-api-check", { - name: "Staging API", - alertChannels: [stagingTeams], - tags: ["staging"], - maxResponseTime: 10000, // More lenient for staging - degradedResponseTime: 5000, - request: { - method: "GET", - url: "https://staging-api.example.com/health", - }, - }) - ``` - - - -## Setting Up Microsoft Teams Webhooks - -Find more information on how to set up a Microsoft Teams workflows in [the Microsoft Teams documentation](/integrations/alerts/msteams). - -## Environment Variables - -Store your Teams webhook URLs securely using environment variables: - -```ts -const teamsChannel = new MSTeamsAlertChannel("teams-alerts", { - name: "Team Notifications", - url: process.env.TEAMS_WEBHOOK_URL!, +### Microsoft Teams Alert Channel Options + + +The target URL created by [creating a Workflow in Microsoft Teams](/integrations/alerts/msteams). + + + +Friendly name to recognize the integration. + + + +Custom payload for the alert message. If this is not specified, we'll send a default payload with basic information about the alert. + +We have [handlebar helpers and variables](/integrations/alerts/webhooks/#using-variables) available for building custom payloads. + +Here's an example payload, using the default one that we provide: + +```ts highlight={4-120} +new MSTeamsAlertChannel('msteams-channel-01', { + name: 'ACME alerts', + url: 'https://prod-24.westus.logic.azure.com:443/workflows/xxxxx', + payload: `{ + "type":"message", + "attachments":[ + { + "contentType":"application/vnd.microsoft.card.adaptive", + "contentUrl":null, + "content":{ + "$schema":"http://adaptivecards.io/schemas/adaptive-card.json", + "type":"AdaptiveCard", + "version":"1.2", + "body":[ + { + "type": "Container", + "items": [ + { + "type": "TextBlock", + "text": "{{ALERT_TITLE}}", + "weight": "Bolder", + "size": "Large", + "style": "heading" + }, + {{#if AI_ANALYSIS_CLASSIFICATION}} + { + "type": "TextBlock", + "text": "AI analysis", + "weight": "Bolder", + "size": "Default", + "style": "heading" + }, + { + "type": "ColumnSet", + "columns": [ + { + "type": "Column", + "width": "stretch", + "items": [ + { + "type": "TextBlock", + "text": "{{AI_ANALYSIS_CLASSIFICATION}}", + "weight": "Bolder", + "wrap": true + }, + { + "type": "TextBlock", + "text": "{{AI_ANALYSIS_ROOT_CAUSE}}", + "wrap": true + } + ] + } + ] + }, + { + "type": "ActionSet", + "actions": [ + { + "type": "Action.OpenUrl", + "title": "Read full analysis", + "url": "{{AI_ANALYSIS_LINK}}", + "style": "positive", + "iconUrl": "icon:Sparkle" + } + ] + }, + {{/if}} + { + "type": "ColumnSet", + "columns": [ + { + "type": "Column", + "width": "stretch", + "items": [ + { + "type": "TextBlock", + "text": "Response time: {{RESPONSE_TIME}}ms", + "wrap": true + }, + { + "type": "TextBlock", + "text": "Location: {{RUN_LOCATION}}", + "wrap": true + }, + { + "type": "TextBlock", + "text": "Timestamp: {{STARTED_AT}}", + "wrap": true + }, + {{#if GROUP_NAME}} + { + "type": "TextBlock", + "text": "Group: {{GROUP_NAME}}", + "wrap": true + }, + {{/if}} + { + "type": "TextBlock", + "text": "Tags: {{#each TAGS}} {{this}} {{#unless @last}},{{/unless}} {{/each}}", + "wrap": true + } + ] + } + ] + } + ] + } + ], + "actions":[ + { + "type":"Action.OpenUrl", + "title":"View in Checkly", + "url":"{{RESULT_LINK}}", + "style": "positive" + } + ] + } + } + ] +}` }) ``` + -```bash -# .env -TEAMS_WEBHOOK_URL=https://prod-24.westus.logic.azure.com:443/workflows/xxxxx -``` - -## Best Practices - - -**Webhook Security**: Keep your Teams webhook URLs secure. Anyone with access to the URL can send messages to your Teams channels. - +### General Alert Channel Options - -**Channel Selection**: Choose appropriate Teams channels for different types of alerts. Consider creating dedicated monitoring channels to avoid noise in general discussion channels. - + diff --git a/constructs/opsgenie-alert-channel.mdx b/constructs/opsgenie-alert-channel.mdx new file mode 100644 index 00000000..c689e304 --- /dev/null +++ b/constructs/opsgenie-alert-channel.mdx @@ -0,0 +1,94 @@ +--- +title: 'OpsgenieAlertChannel Construct' +description: 'Learn how to configure Opsgenie alert channels with the Checkly CLI.' +sidebarTitle: 'Opsgenie' +--- + +import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; +import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx'; + + + +For general information about alerting, see our docs on [the Opsgenie integration](/integrations/incident-management/opsgenie) and [alerting with Checkly](/communicate/alerts/overview/). + + +Sends an alert notification to your Opsgenie account. + + + +```ts Basic Example +import { OpsgenieAlertChannel } from 'checkly/constructs' + +const opsGenieChannel = new OpsgenieAlertChannel('opsgenie-channel-1', { + name: 'My Ops Team', + region: 'EU', + priority: 'P1', + apiKey: 'xxxx123abc' +}) +``` + +```ts Advanced Example +import { OpsgenieAlertChannel } from 'checkly/constructs' + +const opsGenieChannel = new OpsgenieAlertChannel('opsgenie-channel-1', { + name: 'My Ops Team', + region: 'EU', + priority: 'P1', + apiKey: 'xxxx123abc', + sendRecovery: true, + sendFailure: true, + sendDegraded: true, + sslExpiry: true, + sslExpiryThreshold: 30, +}) +``` + + + + + If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel). + + +## Configuration + + + + +Configure Opsgenie-specific settings: + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `name` | `string` | ✅ | - | Friendly name to recognise the integration | +| `region` | `string` | ✅ | - | Opsgenie location, either `EU` or `US` | +| `priority` | `string` | ✅ | - | Severity level, `P1` to `P5` | +| `apiKey` | `string` | ✅ | - | API key for your Opsgenie account | + + + + + + + + + +### Opsgenie Alert Channel Options + + +Friendly name to recognise the integration. + + + +A string representing the Opsgenie location, either `EU` or `US`. + + + +A string representing the severity level, `P1` to `P5`. + + + +An API key for your Opsgenie account. + + +### General Alert Channel Options + + diff --git a/constructs/pagerduty-alert-channel.mdx b/constructs/pagerduty-alert-channel.mdx new file mode 100644 index 00000000..f5224aed --- /dev/null +++ b/constructs/pagerduty-alert-channel.mdx @@ -0,0 +1,87 @@ +--- +title: 'PagerdutyAlertChannel Construct' +description: 'Learn how to configure Pagerduty alert channels with the Checkly CLI.' +sidebarTitle: 'Pagerduty' +--- + +import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; +import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx'; + + + +For general information about alerting, see our docs on [the Pagerduty integration](/integrations/incident-management/pagerduty) and [alerting with Checkly](/communicate/alerts/overview/). + + +Sends an alert notification to a specific service in your Pagerduty account. + + + +```ts Basic Example +import { PagerdutyAlertChannel } from 'checkly/constructs' + +const pagerdutyChannel = new PagerdutyAlertChannel('pagerduty-channel-1', { + account: 'ACME', + serviceName: 'ACME products', + serviceKey: '872b9b58ff4a9n06d0dl9f20487bbqwew' +}) +``` + +```ts Advanced Example +import { PagerdutyAlertChannel } from 'checkly/constructs' + +const pagerdutyChannel = new PagerdutyAlertChannel('pagerduty-channel-1', { + account: 'ACME', + serviceName: 'ACME products', + serviceKey: '872b9b58ff4a9n06d0dl9f20487bbqwew', + sendRecovery: true, + sendFailure: true, + sendDegraded: true, + sslExpiry: true, + sslExpiryThreshold: 30, +}) +``` + + + + + If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel). + + +## Configuration + + + + +Configure Pagerduty-specific settings: + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `account` | `string` | ✅ | - | The name of your Pagerduty account | +| `serviceName` | `string` | ✅ | - | The name of your service in Pagerduty under which the alerts should be nested | +| `serviceKey` | `string` | ✅ | - | The API key created by installing the Checkly integration in Pagerduty. [Install the integration from our UI](https://app.checklyhq.com/alerts/settings/channels/new/pagerduty/) to get this. | + + + + + + + + + +### Pagerduty Alert Channel Options + + +The name of your Pagerduty account. + + + +The name of your service defined in Pagerduty under which the alerts should be nested. + + + +The API key created by installing the Checkly integration in Pagerduty. We advise you to [install the Pagerduty alert channel first from the UI](https://app.checklyhq.com/alerts/settings/channels/new/pagerduty/) to grab the `serviceKey`. + + +### General Alert Channel Options + + diff --git a/constructs/phone-call-alert-channel.mdx b/constructs/phone-call-alert-channel.mdx index 2d5e4df3..32b6e387 100644 --- a/constructs/phone-call-alert-channel.mdx +++ b/constructs/phone-call-alert-channel.mdx @@ -1,44 +1,48 @@ --- title: 'PhoneCallAlertChannel Construct' description: 'Learn how to configure phone call alert channels with the Checkly CLI.' -sidebarTitle: 'Phone Call Alert Channel' +sidebarTitle: 'Phone Call' --- import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; +import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx'; -Learn more about Phone Call alerts in [the Phone Call Alerts documentation](/integrations/alerts/phone-calls). +For general information about alerting, see our docs on [phone call alerts](/integrations/alerts/phone-calls) and [alerting with Checkly](/communicate/alerts/overview/). -Use Phone Call Alerts to make voice calls when checks fail or recover. Phone call alerts are the most immediate form of notification, ideal for critical systems requiring instant attention. +Sends phone calls to the specified phone number. ```ts Basic Example -import { PhoneCallAlertChannel } from "checkly/constructs" +import { PhoneCallAlertChannel } from 'checkly/constructs' -const callChannel = new PhoneCallAlertChannel("call-channel-1", { - phoneNumber: "+1234567890", - name: "Tim's phone", +const callChannel = new PhoneCallAlertChannel('call-channel-1', { + phoneNumber: '+31061234567890', }) ``` ```ts Advanced Example -import { PhoneCallAlertChannel } from "checkly/constructs" +import { PhoneCallAlertChannel } from 'checkly/constructs' -const emergencyCall = new PhoneCallAlertChannel("emergency-call-channel", { - phoneNumber: "+1234567890", - name: "Tim's phone", - sendRecovery: false, // Only call for failures, not recoveries +const callChannel = new PhoneCallAlertChannel('call-channel-1', { + phoneNumber: '+31061234567890', + name: 'Ops on-call', + sendRecovery: false, sendFailure: true, - sendDegraded: false, // Only for complete failures + sendDegraded: false, sslExpiry: true, - sslExpiryThreshold: 3, // Call 3 days before SSL expires + sslExpiryThreshold: 3, }) ``` + + If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel). + + ## Configuration @@ -48,8 +52,8 @@ Configure phone call-specific settings: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| -| `phoneNumber` | `string` | ✅ | - | Phone number in international format (e.g., +1234567890) | -| `name` | `string` | ❌ | - | Friendly name for the phone call alert channel (e.g. "Tim's phone") | +| `phoneNumber` | `string` | ✅ | - | Phone number in international format (e.g., +31061234567890) | +| `name` | `string` | ❌ | - | Friendly name for the phone call alert channel | @@ -60,187 +64,26 @@ Configure phone call-specific settings: -## Phone Call Alert Channel Examples - - - - ```ts - import { PhoneCallAlertChannel, ApiCheck } from "checkly/constructs" - - const emergencyCall = new PhoneCallAlertChannel("emergency-response", { - phoneNumber: "+1555EMERGENCY", - sendFailure: true, - sendRecovery: false, // Don't call for recoveries - sendDegraded: false, // Only complete failures - }) - - new ApiCheck("life-safety-system", { - name: "Life Safety System", - alertChannels: [emergencyCall], - tags: ["life-safety", "critical"], - request: { - method: "GET", - url: "https://life-safety.example.com/health", - }, - }) - ``` - - - - ```ts - import { ApiCheck, PhoneCallAlertChannel } from "checkly/constructs" - - const executiveCall = new PhoneCallAlertChannel("executive-call", { - phoneNumber: "+1555EXEC", // Executive phone number - sendFailure: true, - sendRecovery: true, // Notify of both failures and recoveries - sendDegraded: false, - }) - - new ApiCheck("revenue-critical-api", { - name: "Revenue Critical API", - alertChannels: [executiveCall], - tags: ["revenue-critical", "executive-level"], - request: { - method: "GET", - url: "https://payments.example.com/health", - }, - }) - ``` - - - - ```ts - import { ApiCheck, PhoneCallAlertChannel } from "checkly/constructs" - - const securityCall = new PhoneCallAlertChannel("security-incident", { - phoneNumber: "+1555SECURITY", - sendFailure: true, - sendRecovery: false, - sslExpiry: true, - sslExpiryThreshold: 1, // Call immediately for SSL expiry - }) - - new ApiCheck("security-endpoint", { - name: "Security Endpoint Monitor", - alertChannels: [securityCall], - tags: ["security", "authentication"], - request: { - method: "GET", - url: "https://auth.example.com/security-health", - }, - }) - ``` - - - -## Phone Number Format - -The phone numbers used for SMS alerting need to be in [E.164 format](https://www.twilio.com/docs/glossary/what-e164). Stick to the following rules and you'll be fine: - -- Prepend international access codes with a + sign -- Do not use any white spaces -- Use up to 15 characters - - - - ```ts - // US numbers - const usCall = new PhoneCallAlertChannel('us-call', { - phoneNumber: '+15551234567' // +1 (country code) + area code + number - }) - - // UK numbers - const ukCall = new PhoneCallAlertChannel('uk-call', { - phoneNumber: '+447911123456' // +44 (country code) + mobile number - }) - - // German numbers - const deCall = new PhoneCallAlertChannel('de-call', { - phoneNumber: '+491701234567' // +49 (country code) + mobile number - }) - - // Australian numbers - const auCall = new PhoneCallAlertChannel('au-call', { - phoneNumber: '+61412345678' // +61 (country code) + mobile number - }) - ``` - - - - ```ts - // ❌ Don't use these formats: - - // Missing country code - phoneNumber: '5551234567' - - // With spaces or dashes - phoneNumber: '+1 555-123-4567' - - // With parentheses - phoneNumber: '+1 (555) 123-4567' - - // Domestic format - phoneNumber: '(555) 123-4567' - ``` - - +### Phone Call Alert Channel Options -## Combining with Other Alert Channels + +Phone number to call. -Phone calls should be used as part of a comprehensive alerting strategy: +Each `PhoneCallAlertChannel` supports only one phone number. Phone numbers need to be in [E.164 format](https://www.twilio.com/docs/glossary/what-e164). -```ts -import { - PhoneCallAlertChannel, - SmsAlertChannel, - EmailAlertChannel, - SlackAlertChannel, - ApiCheck, -} from "checkly/constructs" - -// Layered alerting approach -const teamSlack = new SlackAlertChannel("team-slack", { - url: new URL("https://hooks.slack.com/services/YOUR/WEBHOOK/URL"), - channel: "#alerts", -}) - -const oncallEmail = new EmailAlertChannel("oncall-email", { - address: "oncall@example.com", -}) - -const oncallSms = new SmsAlertChannel("oncall-sms", { - phoneNumber: "+1555ONCALL", -}) - -const emergencyCall = new PhoneCallAlertChannel("emergency-call", { - phoneNumber: "+1555EMERGENCY", - sendFailure: true, - sendRecovery: false, // Only call for failures -}) +We only support phone numbers from certain [countries and regions](/integrations/alerts/phone-calls/#supported-countries-and-regions). -new ApiCheck("comprehensive-alerting", { - name: "Critical System with Comprehensive Alerting", - alertChannels: [ - teamSlack, // Immediate team visibility - oncallEmail, // Documentation and detail - oncallSms, // Mobile notification - emergencyCall, // Immediate voice alert - ], - tags: ["critical", "comprehensive"], - request: { - method: "GET", - url: "https://critical.example.com/health", - }, +```ts highlight={2} +new PhoneCallAlertChannel('call-channel-1', { + phoneNumber: '+31061234567890', }) ``` + -## Best Practices + +Friendly name for the phone call alert channel. + - -**Use Sparingly**: Phone calls are the most intrusive form of notification. Reserve them for truly critical systems where immediate human intervention is required. - +### General Alert Channel Options - -**Recovery Notifications**: Consider whether recovery calls are necessary. For some critical systems, knowing when the system recovers is as important as knowing when it fails. - + diff --git a/constructs/slack-alert-channel.mdx b/constructs/slack-alert-channel.mdx index d0496c3e..07acfa1b 100644 --- a/constructs/slack-alert-channel.mdx +++ b/constructs/slack-alert-channel.mdx @@ -1,38 +1,35 @@ --- title: 'SlackAlertChannel Construct' description: 'Learn how to configure Slack alert channels with the Checkly CLI.' -sidebarTitle: 'Slack Alert Channel' +sidebarTitle: 'Slack' --- import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; +import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx'; -Learn more about Slack alerts in [the Slack Alerts documentation](/integrations/alerts/slack). +For general information about alerting, see our docs on [Slack alerts](/integrations/alerts/slack) and [alerting with Checkly](/communicate/alerts/overview/). -Use Slack Alert Channels to send notifications to Slack channels when checks fail or recover. The examples below show how to configure Slack alerting for different scenarios. +Sends alert notifications to a Slack channel via an incoming webhook. ```ts Basic Example -import { SlackAlertChannel } from "checkly/constructs" +import { SlackAlertChannel } from 'checkly/constructs' -const slackChannel = new SlackAlertChannel("slack-channel-1", { - url: new URL( - "https://hooks.slack.com/services/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" - ), - channel: "#ops", +const slackChannel = new SlackAlertChannel('slack-channel-1', { + url: new URL('https://hooks.slack.com/services/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'), + channel: '#ops' }) ``` ```ts Advanced Example -import { SlackAlertChannel } from "checkly/constructs" +import { SlackAlertChannel } from 'checkly/constructs' -const slackChannel = new SlackAlertChannel("team-slack-channel", { - url: new URL( - "https://hooks.slack.com/services/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" - ), - channel: "#monitoring-alerts", +const slackChannel = new SlackAlertChannel('slack-channel-1', { + url: new URL('https://hooks.slack.com/services/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'), + channel: '#ops', sendRecovery: true, sendFailure: true, sendDegraded: true, @@ -43,6 +40,10 @@ const slackChannel = new SlackAlertChannel("team-slack-channel", { + + If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel). + + ## Configuration @@ -52,7 +53,7 @@ Configure Slack-specific settings: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| -| `url` | `URL` | ✅ | - | Slack webhook URL for incoming messages | +| `url` | `URL` | ✅ | - | Slack incoming webhook URL | | `channel` | `string` | ❌ | - | Target Slack channel (e.g., '#ops', '@user') | @@ -66,487 +67,20 @@ Configure Slack-specific settings: ### Slack Alert Channel Options -Slack webhook URL for incoming messages. This is the endpoint where Checkly will send alert notifications. - -**Usage:** - -```ts highlight={2-4} -new SlackAlertChannel("slack-channel", { - url: new URL( - "https://hooks.slack.com/services/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" - ), - channel: "#alerts", -}) -``` - -Examples: - - - -```ts Direct URL -const slackChannel = new SlackAlertChannel("direct-slack", { - url: new URL( - "https://hooks.slack.com/services/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" - ), - channel: "#monitoring", -}) -``` - -```ts Environment Variable -const secureSlack = new SlackAlertChannel("secure-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), // Store securely - channel: "#alerts", -}) -``` - -```ts Multiple Teams -// Different webhook URLs for different teams -const devSlack = new SlackAlertChannel("dev-slack", { - url: new URL(process.env.DEV_SLACK_WEBHOOK_URL!), - channel: "#dev-alerts", -}) +The Slack incoming webhook URL where Checkly will send alert notifications. -const opsSlack = new SlackAlertChannel("ops-slack", { - url: new URL(process.env.OPS_SLACK_WEBHOOK_URL!), - channel: "#ops-alerts", +```ts highlight={2} +new SlackAlertChannel('slack-channel-1', { + url: new URL('https://hooks.slack.com/services/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'), + channel: '#ops' }) ``` - - - -**Use cases**: Team notifications, webhook integration, secure credential storage, multi-team alerting. -Target Slack channel or user for notifications. Can override the default channel configured in the webhook. - -**Usage:** - -```ts highlight={3} -new SlackAlertChannel("channel-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#ops", // Send to #ops channel -}) -``` - -**Examples:** - - - -```ts Channel Notifications -const channelSlack = new SlackAlertChannel("channel-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#monitoring-alerts", // Public channel -}) -``` - -```ts Direct Messages -const dmSlack = new SlackAlertChannel("dm-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "@john.doe", // Direct message to user -}) -``` - -```ts Different Channels for Different Purposes -const criticalSlack = new SlackAlertChannel("critical-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#critical-alerts", -}) - -const performanceSlack = new SlackAlertChannel("performance-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#performance-monitoring", -}) - -const securitySlack = new SlackAlertChannel("security-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#security-alerts", -}) -``` - - - -**Use cases**: Team-specific alerts, direct notifications, alert categorization, noise management. +Target Slack channel or user for notifications. You can specify the target channel to override the default channel configured in the webhook. ### General Alert Channel Options - -Whether to send notifications when checks recover from failure or degraded state. - -**Usage:** - -```ts highlight={4} -new SlackAlertChannel("recovery-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#alerts", - sendRecovery: true, // Send recovery notifications -}) -``` - -**Examples:** - - - -```ts Recovery Notifications -const opsSlack = new SlackAlertChannel("ops-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#ops", - sendRecovery: true, // Get notified when issues are resolved - sendFailure: true, -}) -``` - -```ts Failure Only -const alertsSlack = new SlackAlertChannel("alerts-only", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#critical-alerts", - sendRecovery: false, // Only failures, no recovery notifications - sendFailure: true, - sendDegraded: false, -}) -``` - - - -**Use cases**: Recovery confirmation, operational awareness, noise reduction. - - - -Whether to send notifications when checks fail. - -**Usage:** - -```ts highlight={4} -const slackAlert = new SlackAlertChannel("failure-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#alerts", - sendFailure: true, // Send failure notifications -}) -``` - -**Examples:** - - - -```ts Critical Failures Only -const criticalSlack = new SlackAlertChannel("critical-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#critical-alerts", - sendFailure: true, // Critical failures - sendRecovery: true, - sendDegraded: false, // No degraded alerts -}) -``` - -```ts All Notifications -const comprehensiveSlack = new SlackAlertChannel("all-notifications", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#monitoring", - sendFailure: true, // All failures - sendRecovery: true, - sendDegraded: true, -}) -``` - - - -**Use cases**: Incident response, failure monitoring, operational alerting. - - - -Whether to send notifications when API checks degrade (performance thresholds exceeded but not failed). - -**Usage:** - -```ts highlight={4} -new SlackAlertChannel("performance-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#performance", - sendDegraded: true, // Send degraded performance notifications -}) -``` - -**Examples:** - - - -```ts Performance Monitoring -const performanceSlack = new SlackAlertChannel("performance-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#performance", - sendRecovery: true, - sendFailure: true, - sendDegraded: true, // Alert on degraded performance -}) - -new ApiCheck("performance-check", { - name: "API Performance Check", - maxResponseTime: 3000, - degradedResponseTime: 1500, // Triggers degrade alerts - alertChannels: [performanceSlack], - request: { - method: "GET", - url: "https://api.example.com/slow-endpoint", - }, -}) -``` - -```ts Critical Only -const criticalOnlySlack = new SlackAlertChannel("critical-only", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#critical-alerts", - sendFailure: true, - sendRecovery: true, - sendDegraded: false, // Only complete failures, not performance issues -}) -``` - - - -**Use cases**: Performance monitoring, early warning systems, SLA tracking. - - - - -Whether to send notifications for SSL certificate expiry warnings. - -**Usage:** - -```ts highlight={4} -new SlackAlertChannel("security-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#security", - sslExpiry: true, - sslExpiryThreshold: 30, // Alert 30 days before expiry -}) -``` - -**Examples:** - - - -```ts Security Team Alerts -const securitySlack = new SlackAlertChannel("security-slack", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#security", - sendRecovery: false, - sendFailure: true, - sslExpiry: true, - sslExpiryThreshold: 7, // Alert 7 days before expiry -}) - -new ApiCheck("ssl-cert-check", { - name: "SSL Certificate Check", - alertChannels: [securitySlack], - request: { - method: "GET", - url: "https://secure.example.com", - }, -}) -``` - -```ts Early Warning System -const earlyWarningSlack = new SlackAlertChannel("ssl-early-warning", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#devops", - sslExpiry: true, - sslExpiryThreshold: 60, // Alert 60 days before expiry for planning -}) -``` - - - -**Use cases**: Certificate management, security compliance, proactive maintenance. - - - -Number of days before SSL certificate expiry to send notifications. Only relevant when `sslExpiry` is enabled. - -**Usage:** - -```ts highlight={5} -new SlackAlertChannel('ssl-monitoring', { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: '#devops', - sslExpiry: true, - sslExpiryThreshold: 30 // Alert 30 days before expiry -}) -``` - -Examples: - - - -```ts Last Minute Alert -// Alert close to expiry for urgent action -new SlackAlertChannel("ssl-urgent", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#security", - sslExpiry: true, - sslExpiryThreshold: 7, // 7 days notice -}) -``` - -```ts Multiple Thresholds -// Create multiple channels with different thresholds -const earlyWarning = new SlackAlertChannel("ssl-early", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#planning", - sslExpiry: true, - sslExpiryThreshold: 90, // Planning notification -}) - -const urgentWarning = new SlackAlertChannel("ssl-urgent", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#oncall", - sslExpiry: true, - sslExpiryThreshold: 7, // Urgent notification -}) -``` - - - -**Use cases**: Certificate renewal planning, compliance management, operational scheduling. - - -## Examples - - -```ts Team Channel Alerts - import { SlackAlertChannel, ApiCheck } from "checkly/constructs" - - const teamSlack = new SlackAlertChannel("team-slack", { - url: new URL("https://hooks.slack.com/services/YOUR/WEBHOOK/URL"), - channel: "#dev-team", - }) - - new ApiCheck("api-health-check", { - name: "API Health Check", - alertChannels: [teamSlack], - request: { - method: "GET", - url: "https://api.acme.com/health", - }, - }) -``` - -```ts Critical Alerts Channel - import { ApiCheck, SlackAlertChannel } from "checkly/constructs" - - const criticalSlack = new SlackAlertChannel("critical-slack", { - url: new URL("https://hooks.slack.com/services/YOUR/WEBHOOK/URL"), - channel: "#critical-alerts", - sendRecovery: true, - sendFailure: true, - sendDegraded: false, // Only failures for critical alerts - }) - - new ApiCheck("payment-api-check", { - name: "Payment API Check", - alertChannels: [criticalSlack], - tags: ["critical", "payment"], - request: { - method: "GET", - url: "https://api.acme.com/payments/health", - }, - }) -``` - -```ts Direct Message Alerts - import { ApiCheck, SlackAlertChannel } from "checkly/constructs" - - const dmSlack = new SlackAlertChannel("dm-slack", { - url: new URL("https://hooks.slack.com/services/YOUR/WEBHOOK/URL"), - channel: "@john.doe", // Direct message to user - sendFailure: true, - sendRecovery: false, // Only notify on failures - }) - - new ApiCheck("personal-project-check", { - name: "Personal Project Check", - alertChannels: [dmSlack], - request: { - method: "GET", - url: "https://personal-project.example.com", - }, - }) -``` - -```ts SSL Certificate Monitoring - import { ApiCheck, SlackAlertChannel } from "checkly/constructs" - - const securitySlack = new SlackAlertChannel("security-slack", { - url: new URL("https://hooks.slack.com/services/YOUR/WEBHOOK/URL"), - channel: "#security", - sendFailure: true, - sendRecovery: false, - sslExpiry: true, - sslExpiryThreshold: 7, // Alert 7 days before SSL expires - }) - - new ApiCheck("ssl-cert-check", { - name: "SSL Certificate Check", - alertChannels: [securitySlack], - request: { - method: "GET", - url: "https://secure.acme.com", - }, - }) -``` - -```ts Multiple Channels - import { ApiCheck, SlackAlertChannel } from "checkly/constructs" - - const devSlack = new SlackAlertChannel("dev-slack", { - url: new URL("https://hooks.slack.com/services/YOUR/WEBHOOK/URL"), - channel: "#development", - sendDegraded: true, - }) - - const opsSlack = new SlackAlertChannel("ops-slack", { - url: new URL("https://hooks.slack.com/services/YOUR/WEBHOOK/URL"), - channel: "#operations", - sendFailure: true, - sendRecovery: true, - }) - - new ApiCheck("multi-channel-check", { - name: "Multi-Channel Notifications", - alertChannels: [devSlack, opsSlack], - request: { - method: "GET", - url: "https://api.acme.com/important", - }, - }) -``` - - - -## Setting Up Slack Webhooks - -Find more information on how to set up a new Slack webhook in [the Slack alert channel documentation](/integrations/alerts/slack). - -## Environment Variables - -Store your Slack webhook URL securely using environment variables: - -```ts -const slackChannel = new SlackAlertChannel("slack-channel", { - url: new URL(process.env.SLACK_WEBHOOK_URL!), - channel: "#monitoring", -}) -``` - -```bash -# .env -SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL -``` - - -**Webhook Security**: Keep your Slack webhook URLs secure. Anyone with access to the URL can send messages to your Slack channels. - - - -**Channel Override**: The `channel` parameter can override the default channel configured in your Slack webhook. Use `#channel-name` for channels or `@username` for direct messages. - + diff --git a/constructs/sms-alert-channel.mdx b/constructs/sms-alert-channel.mdx index 8e77073d..aab73aae 100644 --- a/constructs/sms-alert-channel.mdx +++ b/constructs/sms-alert-channel.mdx @@ -1,42 +1,49 @@ --- title: 'SmsAlertChannel Construct' description: 'Learn how to configure SMS alert channels with the Checkly CLI.' -sidebarTitle: 'SMS Alert Channel' +sidebarTitle: 'SMS' --- import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; +import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx'; -Learn more about SMS alerts in [the SMS alert documentation](/integrations/alerts/sms). +For general information about alerting, see our docs on [SMS alerts](/integrations/alerts/sms) and [alerting with Checkly](/communicate/alerts/overview/). -Use SMS Alert Channels to send SMS notifications to phone numbers when checks fail or recover. SMS alerts are ideal for critical alerts that require immediate attention. +Use SMS Alert Channels to send SMS notifications to phone numbers when checks fail or recover. ```ts Basic Example import { SmsAlertChannel } from 'checkly/constructs' -const smsChannel = new SmsAlertChannel("sms-channel-1", { - phoneNumber: "+1234567890", +const smsChannel = new SmsAlertChannel('sms-channel-1', { + name: 'Ops on-call', + phoneNumber: '+31061234567890', }) ``` ```ts Advanced Example import { SmsAlertChannel } from 'checkly/constructs' -const oncallSms = new SmsAlertChannel("oncall-sms-channel", { - phoneNumber: "+1234567890", +const smsChannel = new SmsAlertChannel('sms-channel-1', { + name: 'Ops on-call', + phoneNumber: '+31061234567890', sendRecovery: true, sendFailure: true, - sendDegraded: false, // Only critical failures + sendDegraded: false, sslExpiry: true, - sslExpiryThreshold: 7, // Alert 7 days before SSL expires + sslExpiryThreshold: 7, }) ``` + + If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel). + + ## Configuration @@ -61,453 +68,24 @@ Configure SMS-specific settings: ### SMS Alert Channel Options -Phone number to send SMS notifications to. Each SmsAlertChannel supports only one phone number. - -**Usage:** - -```ts highlight={2} -new SmsAlertChannel("team-sms", { - phoneNumber: "+1234567890", -}) -``` - -**Use cases**: Team notifications, individual alerts, role-based alerting. - - - -Friendly name for the SMS alert channel (e.g. "Tim's phone"). - -**Usage:** - -```ts highlight={3} -new SmsAlertChannel("team-sms", { - name: "Tim's phone", - phoneNumber: "+1234567890", -}) -``` - -**Use cases**: Personalization, user-friendly identification, role-based alerting. - - -### General Alert Channel Options - - -Whether to send notifications when checks recover from failure or degraded state. - -**Usage:** - -```ts highlight={3} -new SmsAlertChannel("recovery-sms", { - phoneNumber: "+1234567890", - sendRecovery: true, // Send recovery notifications -}) -``` - -**Examples:** - - - -```ts Recovery Notifications -const opsSms = new SmsAlertChannel("ops-sms", { - phoneNumber: "+1234567890", - sendRecovery: true, // Get notified when issues are resolved - sendFailure: true, -}) -``` - -```ts Failure Only -const alertsSms = new SmsAlertChannel("alerts-only", { - phoneNumber: "+1234567890", - sendRecovery: false, // Only failures, no recovery notifications - sendFailure: true, -}) -``` - - - -**Use cases**: Recovery confirmation, operational awareness, noise reduction. - - - -Whether to send notifications when checks fail. - -**Usage:** - -```ts highlight={3} -new SmsAlertChannel("failure-sms", { - phoneNumber: "+1234567890", - sendFailure: true, // Send failure notifications -}) -``` - -**Examples:** - - - -```ts Failures Only -const criticalSms = new SmsAlertChannel("critical-sms", { - phoneNumber: "+1234567890", - sendFailure: true, - sendRecovery: false, - sendDegraded: false, -}) -``` - -```ts All Notifications -const comprehensiveSms = new SmsAlertChannel("all-notifications", { - phoneNumber: "+1234567890", - sendFailure: true, - sendRecovery: true, - sendDegraded: true, -}) -``` - - - -**Use cases**: Incident response, failure monitoring, operational alerting. - - - - -Whether to send notifications when API checks degrade (performance thresholds exceeded but not failed). - -**Usage:** - -```ts highlight={3} -new SmsAlertChannel("performance-sms", { - phoneNumber: "+1234567890", - sendDegraded: true, // Send degraded performance notifications -}) -``` +Phone number to send SMS notifications to. -**Use cases**: Performance monitoring, early warning systems, SLA tracking. - - - -Whether to send notifications for SSL certificate expiry warnings. +Each `SmsAlertChannel` supports only one phone number. Phone numbers need to be in [E.164 format](https://www.twilio.com/docs/glossary/what-e164). -**Usage:** +We only support phone numbers from certain [countries and regions](/integrations/alerts/sms#supported-countries-and-regions). ```ts highlight={3} -new SmsAlertChannel("security-sms", { - phoneNumber: "+1234567890", - sslExpiry: true, - sslExpiryThreshold: 30, // Alert 30 days before expiry +new SmsAlertChannel('sms-channel-1', { + name: 'Ops on-call', + phoneNumber: '+31061234567890', }) ``` - -**Use cases**: Certificate management, security compliance, proactive maintenance. - -Number of days before SSL certificate expiry to send notifications. Only relevant when `sslExpiry` is enabled. - -**Usage:** - -```ts highlight={4} -new SmsAlertChannel("ssl-monitoring", { - phoneNumber: "+1234567890", - sslExpiry: true, - sslExpiryThreshold: 30, // Alert 30 days before expiry -}) -``` - -**Use cases**: Certificate renewal planning, compliance management, operational scheduling. + +Friendly name for the SMS alert channel. +### General Alert Channel Options -## SMS Alert Channel Examples - - - - ```ts - import { ApiCheck, SmsAlertChannel } from "checkly/constructs" - - const oncallSms = new SmsAlertChannel("oncall-sms", { - phoneNumber: "+1555123456", - }) - - new ApiCheck("critical-api-check", { - name: "Critical API Endpoint", - alertChannels: [oncallSms], - tags: ["critical", "production"], - request: { - method: "GET", - url: "https://api.example.com/critical", - }, - }) - ``` - - - - ```ts - import { ApiCheck, SmsAlertChannel } from "checkly/constructs" - - const primaryOncall = new SmsAlertChannel("primary-oncall", { - phoneNumber: "+1555123456", - }) - - const secondaryOncall = new SmsAlertChannel("secondary-oncall", { - phoneNumber: "+1555654321", - }) - - const teamLead = new SmsAlertChannel("team-lead", { - phoneNumber: "+1555999888", - sendFailure: true, - sendRecovery: false, // Only failures - }) - - new ApiCheck("payment-api-check", { - name: "Payment API Check", - alertChannels: [primaryOncall, secondaryOncall, teamLead], - request: { - method: "GET", - url: "https://api.example.com/payments/health", - }, - }) - ``` - - - - ```ts - import { ApiCheck, SmsAlertChannel } from "checkly/constructs" - - // US on-call - const usOncall = new SmsAlertChannel("us-oncall", { - phoneNumber: "+15551234567", - }) - - // Europe on-call - const euOncall = new SmsAlertChannel("eu-oncall", { - phoneNumber: "+44123456789", - }) - - // Asia-Pacific on-call - const apacOncall = new SmsAlertChannel("apac-oncall", { - phoneNumber: "+81312345678", - }) - - // Regional API checks - new ApiCheck("us-api-check", { - name: "US API Check", - locations: ["us-east-1", "us-west-2"], - alertChannels: [usOncall], - request: { - method: "GET", - url: "https://us-api.example.com/health", - }, - }) - - new ApiCheck("eu-api-check", { - name: "EU API Check", - locations: ["eu-west-1"], - alertChannels: [euOncall], - request: { - method: "GET", - url: "https://eu-api.example.com/health", - }, - }) - ``` - - - - ```ts - import { ApiCheck, SmsAlertChannel } from "checkly/constructs" - - const criticalSms = new SmsAlertChannel("critical-sms", { - phoneNumber: "+1555CRITICAL", - sendFailure: true, - sendRecovery: true, - sendDegraded: false, // Only for failures - }) - - const warningSms = new SmsAlertChannel("warning-sms", { - phoneNumber: "+1555WARNING", - sendFailure: true, - sendRecovery: false, - sendDegraded: true, // Include degraded performance - }) - - // Critical service - new ApiCheck("critical-service", { - name: "Critical Payment Service", - alertChannels: [criticalSms], - tags: ["critical", "payment"], - request: { - method: "GET", - url: "https://payment.example.com/health", - }, - }) - - // Warning-level service - new ApiCheck("analytics-service", { - name: "Analytics Service", - alertChannels: [warningSms], - maxResponseTime: 5000, - degradedResponseTime: 2000, - tags: ["analytics", "non-critical"], - request: { - method: "GET", - url: "https://analytics.example.com/health", - }, - }) - ``` - - - -## Phone Number Format - -The phone numbers used for SMS alerting need to be in [E.164 format format](https://www.twilio.com/docs/glossary/what-e164). Stick to the following rules and you'll be fine: - -- Prepend international access codes with a + sign -- Do not use any white spaces -- Use up to 15 characters - - - - ```ts - // US numbers - const usPhone = new SmsAlertChannel('us-sms', { - phoneNumber: '+15551234567' // +1 (country code) + area code + number - }) - - // UK numbers - const ukPhone = new SmsAlertChannel('uk-sms', { - phoneNumber: '+447911123456' // +44 (country code) + mobile number - }) - - // German numbers - const dePhone = new SmsAlertChannel('de-sms', { - phoneNumber: '+491701234567' // +49 (country code) + mobile number - }) - ``` - - - - ```ts - // ❌ Don't use these formats: - - // Missing country code - phoneNumber: '5551234567' - - // With spaces or dashes - phoneNumber: '+1 555-123-4567' - - // With parentheses - phoneNumber: '+1 (555) 123-4567' - - // Domestic format - phoneNumber: '(555) 123-4567' - ``` - - - -## Combining with Other Alert Channels - -SMS works well in combination with other notification methods: - -```ts -import { - ApiCheck, - EmailAlertChannel, - SlackAlertChannel, - SmsAlertChannel, -} from "checkly/constructs" - -const criticalSms = new SmsAlertChannel("critical-sms", { - phoneNumber: "+1555CRITICAL", -}) - -const teamEmail = new EmailAlertChannel("team-email", { - address: "dev-team@example.com", -}) - -const slackChannel = new SlackAlertChannel("team-slack", { - url: new URL("https://hooks.slack.com/services/YOUR/WEBHOOK/URL"), - channel: "#alerts", -}) - -new ApiCheck("multi-channel-alerts", { - name: "Multi-Channel Alert Check", - alertChannels: [ - criticalSms, // Immediate SMS for critical issues - teamEmail, // Email for documentation - slackChannel, // Slack for team visibility - ], - request: { - method: "GET", - url: "https://api.example.com/critical-service", - }, -}) -``` - -## Best Practices - - -**SMS Limits**: Be mindful of SMS costs and potential rate limits. Use SMS for truly critical alerts and combine with other notification methods for comprehensive coverage. - - - - - ```ts - import { ApiCheck, SmsAlertChannel } from "checkly/constructs" - - // Use SMS sparingly for the most critical alerts - const emergencySms = new SmsAlertChannel("emergency-sms", { - phoneNumber: "+1555EMERGENCY", - sendFailure: true, - sendRecovery: false, // Reduce SMS volume - sendDegraded: false, // Only failures - }) - - new ApiCheck("life-critical-system", { - name: "Life Critical System", - alertChannels: [emergencySms], - tags: ["life-critical", "emergency"], - request: { - method: "GET", - url: "https://life-critical.example.com/health", - }, - }) - ``` - - - - ```ts - import { - ApiCheck, - EmailAlertChannel, - SmsAlertChannel, - } from "checkly/constructs" - - // Start with less intrusive methods, escalate to SMS - const teamEmail = new EmailAlertChannel("team-email", { - address: "team@example.com", - }) - - const urgentSms = new SmsAlertChannel("urgent-sms", { - phoneNumber: "+1555URGENT", - }) - - // Regular monitoring with email - new ApiCheck("regular-service", { - name: "Regular Service", - alertChannels: [teamEmail], - request: { - method: "GET", - url: "https://api.example.com/regular", - }, - }) - - // Critical service with SMS escalation - new ApiCheck("critical-service", { - name: "Critical Service", - alertChannels: [teamEmail, urgentSms], // Both email and SMS - request: { - method: "GET", - url: "https://api.example.com/critical", - }, - }) - ``` - - + diff --git a/constructs/telegram-alert-channel.mdx b/constructs/telegram-alert-channel.mdx new file mode 100644 index 00000000..ba273fb9 --- /dev/null +++ b/constructs/telegram-alert-channel.mdx @@ -0,0 +1,114 @@ +--- +title: 'TelegramAlertChannel Construct' +description: 'Learn how to configure Telegram alert channels with the Checkly CLI.' +sidebarTitle: 'Telegram' +--- + +import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; +import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx'; + + + +For general information about alerting, see our docs on [the Telegram integration](/integrations/alerts/telegram) and [alerting with Checkly](/communicate/alerts/overview/). + + +Sends alerts to a Telegram channel. + + + +```ts Basic Example +import { TelegramAlertChannel } from 'checkly/constructs' + +const telegramChannel = new TelegramAlertChannel('my-telegramchannel-1', { + name: 'My Telegram channel', + apiKey: 'xxxxxx', + chatId: 'xxxxxx' +}) +``` + +```ts Advanced Example +import { TelegramAlertChannel } from 'checkly/constructs' + +const telegramChannel = new TelegramAlertChannel('my-telegramchannel-1', { + name: 'My Telegram channel', + apiKey: 'xxxxxx', + chatId: 'xxxxxx', + sendRecovery: true, + sendFailure: true, + sendDegraded: true, + sslExpiry: true, + sslExpiryThreshold: 30, +}) +``` + + + + + If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel). + + +## Configuration + + + + +Configure Telegram-specific settings: + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `name` | `string` | ✅ | - | Friendly name to recognise the integration | +| `apiKey` | `string` | ✅ | - | The API key associated with your Telegram bot | +| `chatId` | `string` | ✅ | - | The chat ID of the Telegram channel you want to send alerts to | +| `payload` | `string` | ❌ | Includes basic information about the alert, including a link to the check result. | The message sent to the chat when an alert is triggered | + + + + + + + + + +### Telegram Alert Channel Options + + +Friendly name to recognise the integration. + + + +The API key associated with your Telegram bot. + + + +The chat ID of the Telegram channel you want to send alerts to. + + + +The message sent to the chat when an alert is triggered. If this is not specified, we'll send a default payload with some basic information about the alert. + +We have [handlebar helpers and variables](/integrations/alerts/webhooks/#using-variables) available for building custom payloads. + +```ts highlight={5-16} +new TelegramAlertChannel('my-telegramchannel-1', { + name: 'My Telegram channel', + apiKey: 'xxxxxx', + chatId: 'xxxxxx', + payload: ` + {{ALERT_TITLE}} at {{RUN_LOCATION}} ({{RESPONSE_TIME}}ms) + {{#if AI_ANALYSIS_CLASSIFICATION}} + AI Analysis: {{AI_ANALYSIS_CLASSIFICATION}} + + {{AI_ANALYSIS_ROOT_CAUSE}} + Read full analysis + {{/if}} + + Tags: {{#each TAGS}} {{this}} {{#unless @last}},{{/unless}} {{/each}} + View check result + ` +}) +``` + + +### General Alert Channel Options + + diff --git a/constructs/webhook-alert-channel.mdx b/constructs/webhook-alert-channel.mdx index d5ab46ed..8dce1313 100644 --- a/constructs/webhook-alert-channel.mdx +++ b/constructs/webhook-alert-channel.mdx @@ -1,16 +1,19 @@ --- title: 'WebhookAlertChannel Construct' description: 'Learn how to configure webhook alert channels with the Checkly CLI.' -sidebarTitle: 'Webhook Alert Channel' +sidebarTitle: 'Webhook' --- import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx'; +import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx'; -Learn more about Webhook alerts in [the webhook alert documentation](/integrations/alerts/webhooks). +For general information about alerting, see our docs on [webhook alerts](/integrations/alerts/webhooks) and [alerting with Checkly](/communicate/alerts/overview/). -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. +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](/integrations/alerts/webhooks#using-variables). @@ -29,44 +32,38 @@ const webhookChannel = new WebhookAlertChannel("webhook-channel-1", { ``` ```ts Advanced Example -import { WebhookAlertChannel } from "checkly/constructs" +import { WebhookAlertChannel } from 'checkly/constructs' -const webhookChannel = new WebhookAlertChannel("advanced-webhook", { - name: "Advanced Webhook Channel", - method: "POST", - url: new URL("https://api.example.com/webhooks/alerts"), - headers: [ - { key: "Authorization", value: "Bearer {{API_TOKEN}}" }, - { key: "Content-Type", value: "application/json" }, - { key: "X-Source", value: "Checkly" }, - ], - queryParameters: [ - { key: "source", value: "checkly" }, - { key: "version", value: "v1" }, - ], - template: JSON.stringify({ - alert: { - title: "{{ALERT_TITLE}}", - type: "{{ALERT_TYPE}}", - status: "{{ALERT_TYPE}}", - started_at: "{{STARTED_AT}}", - response_time: "{{RESPONSE_TIME}}ms", - result_link: "{{RESULT_LINK}}", - check: { - name: "{{CHECK_NAME}}", - type: "{{CHECK_TYPE}}", - location: "{{RUN_LOCATION}}", - }, - }, - }), +const webhookChannel = 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: 'myToken' }], + queryParameters: [{ key: 'source', value: 'checkly' }], + 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}}" + }`, sendRecovery: true, sendFailure: true, sendDegraded: true, + sslExpiry: true, + sslExpiryThreshold: 30, }) ``` + + If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel). + + ## Configuration @@ -95,749 +92,77 @@ Configure webhook-specific settings: ### Webhook Alert Channel Options -Target URL for the webhook request. This is where Checkly will send the HTTP request when alerts are triggered. - -**Usage:** +Target URL for the webhook request. ```ts highlight={4} -new WebhookAlertChannel("webhook-channel", { - name: "API Integration", - method: "POST", - url: new URL("https://api.example.com/webhooks/checkly"), -}) -``` - -**Examples:** - - - -```ts Direct URL -const directWebhook = new WebhookAlertChannel("direct-webhook", { - name: "Direct API", - method: "POST", - url: new URL("https://api.example.com/alerts/webhooks"), -}) -``` - -```ts Environment Variable -const secureWebhook = new WebhookAlertChannel("secure-webhook", { - name: "Secure Webhook", - method: "POST", - url: new URL(process.env.WEBHOOK_URL!), // Store securely -}) -``` - -```ts Service-Specific URLs -// Discord -const discordWebhook = new WebhookAlertChannel("discord-webhook", { - name: "Discord", - method: "POST", - url: new URL("https://discord.com/api/webhooks/123456789/abcdef"), -}) - -// Pushover -const pushoverWebhook = new WebhookAlertChannel("pushover-webhook", { - name: "Pushover", - method: "POST", - url: new URL("https://api.pushover.net/1/messages.json"), +new WebhookAlertChannel('webhook-channel-1', { + name: 'Pushover webhook', + method: 'POST', + url: new URL('https://api.pushover.net/1/messages.json'), }) ``` - - - -**Use cases**: Service integration, webhook endpoints, secure URL storage, API communication. -HTTP method for the webhook request. Supported methods: `GET`, `POST`, `PUT`, `PATCH`, `HEAD`, `DELETE`. - -**Usage:** - -```ts highlight={3} -new WebhookAlertChannel("webhook-channel", { - name: "API Integration", - method: "POST", // Most common for webhooks - url: new URL("https://api.example.com/webhooks"), -}) -``` - -**Examples:** - - - -```ts POST Method (Most Common) -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}}", - }), -}) -``` - -```ts GET Method -const getWebhook = new WebhookAlertChannel("get-webhook", { - name: "GET Webhook", - method: "GET", - url: new URL("https://api.example.com/notify"), - queryParameters: [ - { key: "alert_type", value: "{{ALERT_TYPE}}" }, - { key: "check_name", value: "{{CHECK_NAME}}" }, - ], -}) -``` - -```ts PUT Method -const putWebhook = new WebhookAlertChannel("put-webhook", { - name: "PUT Webhook", - method: "PUT", - url: new URL("https://api.example.com/alerts/update"), - template: JSON.stringify({ - alert_id: "checkly-{{CHECK_NAME}}", - status: "{{ALERT_TYPE}}", - timestamp: "{{STARTED_AT}}", - }), -}) -``` - - - -**Use cases**: RESTful API integration, service-specific requirements. +The HTTP method, either `GET`, `POST`, `PUT`, `PATCH`, `HEAD` or `DELETE`. -Friendly name for the webhook channel to identify it in your Checkly dashboard. - -**Usage:** - -```ts highlight={2} -new WebhookAlertChannel("webhook-channel", { - name: "Custom API Integration", - method: "POST", - url: new URL("https://api.example.com/webhooks"), -}) -``` - -**Examples:** - - - -```ts Service-Based Names -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" - ), -}) -``` - -```ts Purpose-Based Names -const monitoringWebhook = new WebhookAlertChannel("monitoring-webhook", { - name: "Monitoring System Integration", - method: "POST", - url: new URL("https://monitoring.example.com/alerts"), -}) - -const securityWebhook = new WebhookAlertChannel("security-webhook", { - name: "Security Incident System", - method: "POST", - url: new URL("https://security.example.com/incidents"), -}) -``` - - - -**Use cases**: Integration identification, operational clarity. +Friendly name for the webhook channel. -Request body template (commonly JSON) with Handlebars-style variables that are replaced with alert data. - -**Usage:** - -```ts highlight={5-8} -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:** - - - -```ts Basic Template -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}}", - }), -}) -``` - -```ts Rich Template -const richWebhook = new WebhookAlertChannel("rich-webhook", { - name: "Rich Template", - method: "POST", - url: new URL("https://api.example.com/notifications"), - template: JSON.stringify({ - alert: { - title: "{{ALERT_TITLE}}", - type: "{{ALERT_TYPE}}", - started_at: "{{STARTED_AT}}", - response_time: "{{RESPONSE_TIME}}ms", - check: { - name: "{{CHECK_NAME}}", - type: "{{CHECK_TYPE}}", - location: "{{RUN_LOCATION}}", - }, - links: { - result: "{{RESULT_LINK}}", - }, - }, - }), -}) -``` - -```ts Plain Text Template -const textWebhook = new WebhookAlertChannel("text-webhook", { - name: "Text Webhook", - method: "POST", - url: new URL("https://api.example.com/simple"), - template: - "Check {{CHECK_NAME}} is {{ALERT_TYPE}} - Response time: {{RESPONSE_TIME}}ms - {{RESULT_LINK}}", -}) -``` - - - -**Use cases**: Custom message formatting, service-specific payloads, data transformation. - - - -Array of HTTP headers to include in the webhook request. Each header is an object with `key` and `value` properties. - -**Usage:** - -```ts highlight={5-8} -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:** - - - -```ts Authentication Headers -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" }, - ], -}) -``` - -```ts Custom Headers -const customWebhook = new WebhookAlertChannel("custom-webhook", { - name: "Custom Headers", - method: "POST", - url: new URL("https://api.example.com/alerts"), - headers: [ - { key: "X-Source", value: "Checkly" }, - { key: "X-Alert-Version", value: "v1" }, - { key: "X-Severity", value: "{{ALERT_TYPE}}" }, - { key: "User-Agent", value: "Checkly-Webhook/1.0" }, - ], -}) -``` - - - -**Use cases**: Authentication, content type specification, custom metadata, service requirements. - - - -Array of query parameters to include in the webhook URL. Each parameter is an object with `key` and `value` properties. - -**Usage:** - -```ts highlight={5-8} -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}}" }, - ], -}) -``` +The request body template, usually JSON. You can use [Handlebars-style template variables]((/integrations/alerts/webhooks#template-variables)) to add custom data to the template. -**Examples:** - - - -```ts GET Request with Parameters -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}}" }, - ], -}) -``` - -```ts Metadata Parameters -const metadataWebhook = new WebhookAlertChannel('metadata-webhook', { - name: 'Metadata Webhook', +```ts highlight={5-14} +new WebhookAlertChannel('webhook-channel-1', { + name: 'Pushover webhook', method: 'POST', - url: new URL('https://api.example.com/webhooks'), - queryParameters: [ - { key: 'version', value: 'v1' }, - { key: 'source', value: 'monitoring' }, - { key: 'team', value: 'platform' }, - { key: 'severity', value: 'high' } - ] + 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}}" + }` }) ``` - -```ts Dynamic Parameters -const dynamicWebhook = new WebhookAlertChannel('dynamic-webhook', { - name: 'Dynamic Parameters', - method: 'GET', - url: new URL('https://api.example.com/alerts'), - queryParameters: [ - { key: 'check_id', value: '{{CHECK_NAME}}' }, - { key: 'alert_status', value: '{{ALERT_TYPE}}' }, - { key: 'timestamp', value: '{{STARTED_AT}}' }, - { key: 'tags', value: '{{TAGS}}' } - ] -}) -``` - - - -**Use cases**: API requirements, metadata passing, GET request data, service routing. -### General Alert Channel Options - - -Whether to send webhook requests when checks recover from failure or degraded state. - -**Usage:** - -```ts highlight={5} -new WebhookAlertChannel("recovery-webhook", { - name: "Recovery Notifications", - method: "POST", - url: new URL(process.env.WEBHOOK_URL!), - sendRecovery: true, // Send webhooks for recovery notifications -}) -``` - -**Examples:** - - - -```ts Recovery Notifications -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, -}) -``` - -```ts Failure Only -const alertsWebhook = new WebhookAlertChannel("alerts-only", { - name: "Critical Alerts Only", - method: "POST", - url: new URL(process.env.CRITICAL_WEBHOOK_URL!), - sendRecovery: false, // Only failures, no recovery notifications - sendFailure: true, -}) -``` - - - -**Use cases**: Recovery confirmation, operational awareness, noise reduction. - - - -Whether to send webhook requests when checks fail. - -**Usage:** - -```ts highlight={5} -new WebhookAlertChannel("failure-webhook", { - name: "Failure Notifications", - method: "POST", - url: new URL(process.env.WEBHOOK_URL!), - sendFailure: true, // Send webhooks for failure notifications -}) -``` - -**Examples:** - - - -```ts Critical Failures Only -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 -}) -``` - -```ts All Notifications -const comprehensiveWebhook = new WebhookAlertChannel("all-notifications", { - name: "All Monitoring Alerts", - method: "POST", - url: new URL(process.env.MONITORING_WEBHOOK_URL!), - sendFailure: true, // All failures - sendRecovery: true, - sendDegraded: true, -}) -``` - - - -**Use cases**: Incident response, failure monitoring, operational alerting. - - - -Whether to send webhook requests when API checks degrade (performance thresholds exceeded but not failed). - -**Usage:** + +An array of `{ key, value }` objects to define HTTP headers. ```ts highlight={5} -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:** - - - -```ts Performance Monitoring -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", - }, -}) -``` - -```ts Critical Only -const criticalOnlyWebhook = new WebhookAlertChannel("critical-only", { - name: "Critical Alerts Only", - method: "POST", - url: new URL(process.env.CRITICAL_WEBHOOK_URL!), - sendFailure: true, - sendRecovery: true, - sendDegraded: false, // Only complete failures, not performance issues +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' }], }) ``` - - - -**Use cases**: Performance monitoring, early warning systems, SLA tracking. - -Whether to send webhook requests for SSL certificate expiry warnings. - -**Usage:** + +An array of `{ key, value }` objects to define query parameters. ```ts highlight={5} -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:** - - - -```ts Security Team Alerts -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", - }, -}) -``` - -```ts Early Warning System -const earlyWarningWebhook = new WebhookAlertChannel("ssl-early-warning", { - name: "SSL Early Warning", - method: "POST", - url: new URL(process.env.DEVOPS_WEBHOOK_URL!), - sslExpiry: true, - sslExpiryThreshold: 60, // Alert 60 days before expiry for planning +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' }], }) ``` - - - -**Use cases**: Certificate management, security compliance, proactive maintenance. - -Number of days before SSL certificate expiry to send webhook requests. Only relevant when `sslExpiry` is enabled. - -**Usage:** - -```ts highlight={6} -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:** - - - -```ts Conservative Warning -// 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 -}) -``` - -```ts Last Minute Alert -// Alert close to expiry for urgent action -new WebhookAlertChannel("ssl-urgent", { - name: "SSL Urgent Alert", - method: "POST", - url: new URL(process.env.SECURITY_WEBHOOK_URL!), - sslExpiry: true, - sslExpiryThreshold: 7, // 7 days notice -}) -``` - -```ts Multiple Thresholds -// Create multiple channels with different thresholds -const earlyWarning = new WebhookAlertChannel("ssl-early", { - name: "SSL Planning Notification", - method: "POST", - url: new URL(process.env.PLANNING_WEBHOOK_URL!), - sslExpiry: true, - sslExpiryThreshold: 90, // Planning notification -}) - -const urgentWarning = new WebhookAlertChannel("ssl-urgent", { - name: "SSL Urgent Notification", - method: "POST", - url: new URL(process.env.ONCALL_WEBHOOK_URL!), - sslExpiry: true, - sslExpiryThreshold: 7, // Urgent notification -}) -``` - - - -**Use cases**: Certificate renewal planning, compliance management, operational scheduling. + +Secret token that you can use to validate the authenticity of the webhook and its payload. [Learn more about webhook secrets.](/integrations/alerts/webhooks#webhook-secrets) -## Template Configuration - -Learn more about using environment and predefined variables in your webhook template in [the webhook documentation](/integrations/alerts/webhooks#template-variables). - - -## Examples - - -```ts Pushover Notifications -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, - }), -}) -``` - -```ts Discord Webhook -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" - ), - headers: [{ key: "Content-Type", value: "application/json" }], - template: JSON.stringify({ - content: null, - embeds: [ - { - title: "{{ALERT_TITLE}}", - description: - "Check: {{CHECK_NAME}}\nLocation: {{RUN_LOCATION}}\nResponse Time: {{RESPONSE_TIME}}ms", - timestamp: "{{STARTED_AT}}", - footer: { - text: "Checkly Monitoring", - }, - fields: [ - { - name: "View Result", - value: "[Open in Checkly]({{RESULT_LINK}})", - inline: false, - }, - ], - }, - ], - }), -}) -``` - -```ts Custom API Integration -const customApiWebhook = new WebhookAlertChannel("custom-api-webhook", { - name: "Custom API Integration", - method: "POST", - url: new URL("https://api.mycompany.com/alerts"), - headers: [ - { key: "Authorization", value: "Bearer {{API_SECRET}}" }, - { key: "Content-Type", value: "application/json" }, - { key: "X-Checkly-Source", value: "monitoring" }, - ], - queryParameters: [ - { key: "severity", value: "high" }, - { key: "team", value: "platform" }, - ], - template: JSON.stringify({ - event: { - type: "monitoring_alert", - title: "{{ALERT_TITLE}}", - description: "{{CHECK_NAME}} monitoring alert", - timestamp: "{{STARTED_AT}}", - metadata: { - check_name: "{{CHECK_NAME}}", - check_type: "{{CHECK_TYPE}}", - location: "{{RUN_LOCATION}}", - response_time_ms: "{{RESPONSE_TIME}}", - tags: "{{TAGS}}", - result_url: "{{RESULT_LINK}}", - }, - }, - }), - sendFailure: true, - sendRecovery: true, - sendDegraded: false, -}) -``` - - - -## Environment Variables in Templates - -Use environment variables in your webhook templates for sensitive data: - -```ts -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}}", - }), -}) -``` +### General Alert Channel Options - -**Security**: Be careful with sensitive data in webhook templates. Use environment variables for API tokens and secrets. - + diff --git a/docs.json b/docs.json index 498c008d..4707d982 100644 --- a/docs.json +++ b/docs.json @@ -481,12 +481,17 @@ { "group": "Alert Channels", "pages": [ + "constructs/alert-channel", "constructs/email-alert-channel", "constructs/sms-alert-channel", "constructs/phone-call-alert-channel", "constructs/slack-alert-channel", + "constructs/webhook-alert-channel", + "constructs/opsgenie-alert-channel", + "constructs/pagerduty-alert-channel", + "constructs/incidentio-alert-channel", "constructs/msteams-alert-channel", - "constructs/webhook-alert-channel" + "constructs/telegram-alert-channel" ] }, "constructs/retry-strategy", diff --git a/snippets/alert-channel-options-table.mdx b/snippets/alert-channel-options-table.mdx index b395df00..814add27 100644 --- a/snippets/alert-channel-options-table.mdx +++ b/snippets/alert-channel-options-table.mdx @@ -4,6 +4,6 @@ Configure common alert channel properties: |----------|------|----------|---------|-------------| | `sendRecovery` | `boolean` | ❌ | `true` | Send notifications when checks recover | | `sendFailure` | `boolean` | ❌ | `true` | Send notifications when checks fail | -| `sendDegrade` | `boolean` | ❌ | `false` | Send notifications when checks degrade (API checks only) | +| `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 | diff --git a/snippets/alert-channel-options-text.mdx b/snippets/alert-channel-options-text.mdx index 8f341ae3..13edf097 100644 --- a/snippets/alert-channel-options-text.mdx +++ b/snippets/alert-channel-options-text.mdx @@ -1,122 +1,41 @@ - -Whether to send notifications when checks recover from failure or degraded state. - -**Usage:** - -```ts -new EmailAlertChannel("recovery-email", { - address: "ops@acme.com", - sendRecovery: true, // Send recovery notifications -}) -``` - -**Examples:** - - - -```ts Recovery Notifications -const opsEmail = new EmailAlertChannel("ops-email", { - address: "ops@acme.com", - sendRecovery: true, // Get notified when issues are resolved - sendFailure: true, -}) -``` +These options are valid for all alert channels types. -```ts Failure Only -const alertsEmail = new EmailAlertChannel("alerts-only", { - address: "alerts@acme.com", - sendRecovery: false, // Only failures, no recovery notifications - sendFailure: true, -}) -``` - - - -**Use cases**: Recovery confirmation, operational awareness, noise reduction. + +Whether to send notifications when checks recover from a [failed or degraded state](/communicate/alerts/overview/#alert-channels). Default value is `true`. -Whether to send notifications when checks fail. - -**Usage:** - -```ts -new EmailAlertChannel("failure-email", { - address: "oncall@acme.com", - sendFailure: true, // Send failure notifications -}) -``` - -**Examples:** - - - -```ts Failures Only -const criticalEmail = new EmailAlertChannel("critical-email", { - address: "oncall@acme.com", - sendFailure: true, - sendRecovery: false, - sendDegraded: false, -}) -``` - -```ts All Notifications -const comprehensiveEmail = new EmailAlertChannel("all-notifications", { - address: "monitoring@acme.com", - sendFailure: true, - sendRecovery: true, - sendDegraded: true, -}) -``` - - - -**Use cases**: Incident response, failure monitoring, operational alerting. +Whether to send notifications when checks [fail](/communicate/alerts/overview/#alert-channels). Default value is `true`. - -Whether to send notifications when API checks degrade (performance thresholds exceeded but not failed). - -**Usage:** - -```ts -new EmailAlertChannel("performance-email", { - address: "performance-team@acme.com", - sendDegraded: true, // Send degraded performance notifications -}) -``` - -**Use cases**: Performance monitoring, early warning systems, SLA tracking. +Whether to send notifications when checks [become degraded](/communicate/alerts/overview/#alert-channels). Default value is `false`. -Whether to send notifications for SSL certificate expiry warnings. - -**Usage:** +Whether to send notifications when a SSL/TLS certificate is about to expire. Default value is `false`. -```ts -new EmailAlertChannel("security-email", { - address: "security@acme.com", +```ts highlight={3} +new EmailAlertChannel("email-channel-1", { + address: "alerts@acme.com", sslExpiry: true, sslExpiryThreshold: 30, // Alert 30 days before expiry }) ``` -**Use cases**: Certificate management, security compliance, proactive maintenance. +[Learn more about SSL alerts.](/communicate/alerts/ssl-expiration/) -Number of days before SSL certificate expiry to send notifications. Only relevant when `sslExpiry` is enabled. +Number of days before the SSL/TLS certificate expiry date to send notifications. Only relevant when `sslExpiry` is enabled. Default value is `30`. -Usage: -```ts -new EmailAlertChannel("ssl-monitoring", { - address: "devops@acme.com", +```ts highlight={4} +new EmailAlertChannel("email-channel-1", { + address: "alerts@acme.com", sslExpiry: true, sslExpiryThreshold: 30, // Alert 30 days before expiry }) ``` -**Use cases**: Certificate renewal planning, compliance management, operational scheduling. +[Learn more about SSL alerts.](/communicate/alerts/ssl-expiration/)