From 705c3ba69ef70eb3928f2dc7bf89604cd3e51d71 Mon Sep 17 00:00:00 2001 From: pijiang <419471640@qq.com> Date: Mon, 21 Sep 2026 11:06:34 +0800 Subject: [PATCH] docs: add Checkly alert integration --- docs.json | 2 + .../alert-sources/checkly.mdx | 133 ++++++++++++++++ integration-docs/src/doc-map.mjs | 1 + .../alert-sources/checkly.mdx | 147 ++++++++++++++++++ 4 files changed, 283 insertions(+) create mode 100644 en/on-call/integration/alert-integration/alert-sources/checkly.mdx create mode 100644 zh/on-call/integration/alert-integration/alert-sources/checkly.mdx diff --git a/docs.json b/docs.json index 1520dfe8..2ebfaa80 100644 --- a/docs.json +++ b/docs.json @@ -1682,6 +1682,7 @@ "zh/on-call/integration/alert-integration/alert-sources/datadog", "zh/on-call/integration/alert-integration/alert-sources/new-relic", "zh/on-call/integration/alert-integration/alert-sources/sumo-logic", + "zh/on-call/integration/alert-integration/alert-sources/checkly", "zh/on-call/integration/alert-integration/alert-sources/zabbix", "zh/on-call/integration/alert-integration/alert-sources/flashcat", "zh/on-call/integration/alert-integration/alert-sources/open-falcon", @@ -3053,6 +3054,7 @@ "en/on-call/integration/alert-integration/alert-sources/datadog", "en/on-call/integration/alert-integration/alert-sources/new-relic", "en/on-call/integration/alert-integration/alert-sources/sumo-logic", + "en/on-call/integration/alert-integration/alert-sources/checkly", "en/on-call/integration/alert-integration/alert-sources/zabbix", "en/on-call/integration/alert-integration/alert-sources/flashcat", "en/on-call/integration/alert-integration/alert-sources/open-falcon", diff --git a/en/on-call/integration/alert-integration/alert-sources/checkly.mdx b/en/on-call/integration/alert-integration/alert-sources/checkly.mdx new file mode 100644 index 00000000..916c3be8 --- /dev/null +++ b/en/on-call/integration/alert-integration/alert-sources/checkly.mdx @@ -0,0 +1,133 @@ +--- +title: "Checkly alert integration" +description: "Send Checkly failure, degradation, recovery, and SSL certificate alerts to Flashduty On-call through a Webhook Alert Channel." +keywords: ["alert integration", "Checkly", "webhook", "synthetic monitoring", "API monitoring"] +--- + +Use a Checkly Webhook Alert Channel to send check-state changes to Flashduty On-call. Failure, degradation, continued failure, and recovery notifications for one Check update the same Flashduty alert. + +
+ +## In Flashduty On-call +--- + +Create either a dedicated or shared **Checkly** alert integration and copy its complete Push URL. + +
+ +## Configure Checkly +--- + + + + +1. In Checkly, open **Alert Settings** +2. Click **Add more channels** and select **Webhook** +3. Enter `Flashduty` as the name +4. Select `POST` as the method +5. Paste the complete Flashduty integration Push URL into URL +6. Add `Content-Type: application/json` under Headers + + + + + +1. Enable **Failure**, **Degradation**, and **Recovery** under **Notification events** +2. Optionally enable **SSL certificate expirations** +3. Subscribe the Checks or Check Groups that should send notifications to Flashduty + +Recovery must be enabled. Otherwise, a recovered Check cannot recover its existing Flashduty alert. + + + + + +Replace Body with this complete JSON template: + +```json +{ + "alert_type": "{{ALERT_TYPE}}", + "alert_title": "{{ALERT_TITLE}}", + "check_id": "{{CHECK_ID}}", + "check_result_id": "{{CHECK_RESULT_ID}}", + "check_name": "{{CHECK_NAME}}", + "check_type": "{{CHECK_TYPE}}", + "group_name": "{{GROUP_NAME}}", + "is_reminder": "{{IS_REMINDER}}", + "reminder_sequence": "{{REMINDER_SEQUENCE}}", + "region": "{{REGION}}", + "run_location": "{{RUN_LOCATION}}", + "started_at": "{{STARTED_AT}}", + "response_time": "{{RESPONSE_TIME}}", + "response_status_code": "{{API_CHECK_RESPONSE_STATUS_CODE}}", + "response_status_text": "{{API_CHECK_RESPONSE_STATUS_TEXT}}", + "result_link": "{{RESULT_LINK}}", + "error_message": "{{CHECK_ERROR_MESSAGE}}", + "tags": [{{#each TAGS}}"{{this}}"{{#unless @last}},{{/unless}}{{/each}}] +} +``` + +Keep `alert_type` and `check_id`. Never add API keys, tokens, passwords, cookies, or other secrets to the payload. + + + + + +Move one subscribed Check through failure, degradation, and recovery. Confirm that one Flashduty alert is triggered, updated, and recovered. + +A Checkly test notification or webhook HTTP 200 proves connectivity only. Use real Check state changes to verify Alert Key correlation and recovery. + + + + +## Alert Key +--- + +Normal check-state notifications use the trimmed `check_id` (Checkly variable `CHECK_ID`) as the Alert Key. Titles, errors, run locations, response times, result IDs, and alert-state changes do not affect it. + + +If `check_id` is missing or empty, Flashduty accepts the request and generates a random UUID for that notification. These notifications cannot correlate: a later update or recovery without `check_id` cannot find the earlier alert. + + +`ALERT_SSL` is an independent one-shot Warning event. It always receives a new random UUID, even when the payload includes `check_id`, and does not update or recover the Check's normal state alert. + +## Status and severity +--- + +| Checkly `ALERT_TYPE` | Flashduty status | Flashduty severity | +| :--- | :--- | :--- | +| `ALERT_FAILURE`, `ALERT_FAILURE_REMAIN`, `ALERT_DEGRADED_FAILURE` | Active | Critical | +| `ALERT_DEGRADED`, `ALERT_DEGRADED_REMAIN`, `ALERT_FAILURE_DEGRADED` | Active | Warning | +| `ALERT_RECOVERY` | Recovered | Critical | +| `ALERT_DEGRADED_RECOVERY` | Recovered | Warning | +| `ALERT_SSL` | Active, one-shot | Warning | +| `NO_ALERT` | Ignored; no event is created | - | + +An empty or unknown `alert_type` returns an invalid-parameter response. Recovery is determined only by `alert_type`, not by the title or error text. + +## Labels and description +--- + +Flashduty creates these labels: + +- `check` and `source=checkly` +- `check_id` and `checkly_alert_type` +- `check_name`, `check_type`, and `group_name` +- `region` and `run_location` +- `is_reminder` and `reminder_sequence` +- JSON-encoded `tags` + +`check_result_id` is a high-cardinality per-run value and is not stored as a label. The bounded alert description contains the error, response status, response time, start time, and result link. + +## Delivery and troubleshooting +--- + +Checkly retries a failed webhook delivery up to five times at approximately 20-second intervals. Use Checkly's Alert Notification Log to inspect the final delivery result. + +- **Flashduty returns an invalid-parameter error**: verify that Body is valid JSON, matches the complete template, and contains a supported `alert_type` +- **One Check creates multiple alerts**: confirm that every notification carries the same non-empty `check_id` +- **The alert does not recover**: enable Recovery and confirm that the recovery payload has the same `check_id` as the trigger +- **No degradation alert arrives**: enable Degradation and configure a degradation condition on the Check +- **No notification arrives**: confirm that the Check or Check Group subscribes to this Webhook Channel, then inspect the Alert Notification Log + +See [Alerting With Checkly](https://www.checklyhq.com/docs/alerting-and-retries/custom-alerts/) for Checkly's state-transition model. diff --git a/integration-docs/src/doc-map.mjs b/integration-docs/src/doc-map.mjs index 32eb494e..e39ad1ca 100644 --- a/integration-docs/src/doc-map.mjs +++ b/integration-docs/src/doc-map.mjs @@ -66,6 +66,7 @@ export const docMap = { Datadog: `${alertBase}/datadog.mdx`, NewRelic: `${alertBase}/new-relic.mdx`, SumoLogic: `${alertBase}/sumo-logic.mdx`, + Checkly: `${alertBase}/checkly.mdx`, AliyunPrometheus: `${alertBase}/aliyun-prometheus.mdx`, AliyunDataWorksOp: `${alertBase}/aliyun-dataworks-op.mdx`, HttpPull: `${alertBase}/http-pull.mdx`, diff --git a/zh/on-call/integration/alert-integration/alert-sources/checkly.mdx b/zh/on-call/integration/alert-integration/alert-sources/checkly.mdx new file mode 100644 index 00000000..f3c8059b --- /dev/null +++ b/zh/on-call/integration/alert-integration/alert-sources/checkly.mdx @@ -0,0 +1,147 @@ +--- +title: "Checkly 告警集成" +description: "通过 Webhook Alert Channel 将 Checkly 的失败、性能降级、恢复和 SSL 证书告警同步到 Flashduty On-call。" +keywords: ["告警集成", "Checkly", "Webhook", "合成监控", "API 监控"] +--- + +通过 Checkly Webhook Alert Channel 将检查状态同步到 Flashduty On-call。同一个 Check 的失败、降级、持续异常和恢复通知会更新同一条 Flashduty 告警。 + +
+ +## 在 Flashduty On-call +--- + +您可通过以下两种方式获取集成推送地址，任选其一即可。 + +### 使用专属集成 + +1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间 +2. 选择 **集成数据**，点击 **添加一个集成** +3. 选择 **Checkly**，点击 **保存** +4. 打开生成的集成卡片，复制 **推送地址** + +### 使用共享集成 + +1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件** +2. 选择 **Checkly**，填写集成名称 +3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则 +4. 点击 **保存**，复制生成的 **推送地址** + +
+ +## 在 Checkly 中配置 +--- + + + + +1. 登录 Checkly，进入 **Alert Settings** +2. 点击 **Add more channels**，选择 **Webhook** +3. 名称填写 `Flashduty` +4. Method 选择 `POST` +5. 将 Flashduty 集成的完整推送地址粘贴到 URL +6. 在 Headers 中增加 `Content-Type: application/json` + + + + + +1. 在 **Notification events** 中启用 **Failure**、**Degradation** 和 **Recovery** +2. 如需接收证书到期提醒，再启用 **SSL certificate expirations** +3. 在订阅范围中选择需要发送到 Flashduty 的 Checks 或 Check Groups + +必须启用 Recovery，否则 Checkly 恢复后，Flashduty 中的原告警不会自动恢复。 + + + + + +将 Body 替换为以下完整 JSON 模板： + +```json +{ + "alert_type": "{{ALERT_TYPE}}", + "alert_title": "{{ALERT_TITLE}}", + "check_id": "{{CHECK_ID}}", + "check_result_id": "{{CHECK_RESULT_ID}}", + "check_name": "{{CHECK_NAME}}", + "check_type": "{{CHECK_TYPE}}", + "group_name": "{{GROUP_NAME}}", + "is_reminder": "{{IS_REMINDER}}", + "reminder_sequence": "{{REMINDER_SEQUENCE}}", + "region": "{{REGION}}", + "run_location": "{{RUN_LOCATION}}", + "started_at": "{{STARTED_AT}}", + "response_time": "{{RESPONSE_TIME}}", + "response_status_code": "{{API_CHECK_RESPONSE_STATUS_CODE}}", + "response_status_text": "{{API_CHECK_RESPONSE_STATUS_TEXT}}", + "result_link": "{{RESULT_LINK}}", + "error_message": "{{CHECK_ERROR_MESSAGE}}", + "tags": [{{#each TAGS}}"{{this}}"{{#unless @last}},{{/unless}}{{/each}}] +} +``` + +请保留 `alert_type` 和 `check_id`。不要在 Payload 中加入 API Key、Token、密码、Cookie 或其他敏感信息。 + + + + + +让一个已订阅的 Check 依次进入失败、降级和恢复状态，确认 Flashduty 中同一条告警依次触发、更新并恢复。 + +Checkly 的测试发送或 Webhook HTTP 200 只能证明地址可达，不能证明 Alert Key 关联和恢复行为。请使用真实 Check 状态变化完成验证。 + + + + +## Alert Key +--- + +普通检查状态通知使用去除首尾空格后的 `check_id`（Checkly 变量 `CHECK_ID`）作为 Alert Key。标题、错误、执行区域、响应时间、结果 ID 和告警状态变化都不会改变 Alert Key。 + + +当 `check_id` 缺失或为空时，Flashduty 不会拒绝请求，而是为本次通知生成随机 UUID。此时不同通知无法关联：后续更新或恢复不能命中之前同样缺少 `check_id` 的告警。 + + +`ALERT_SSL` 是独立的单次 Warning 事件，即使 Payload 中有 `check_id`，也会使用新的随机 UUID。它不会更新或恢复该 Check 的普通状态告警。 + +## 状态和告警等级 +--- + +| Checkly `ALERT_TYPE` | Flashduty 状态 | Flashduty 等级 | +| :--- | :--- | :--- | +| `ALERT_FAILURE`、`ALERT_FAILURE_REMAIN`、`ALERT_DEGRADED_FAILURE` | 活动 | Critical | +| `ALERT_DEGRADED`、`ALERT_DEGRADED_REMAIN`、`ALERT_FAILURE_DEGRADED` | 活动 | Warning | +| `ALERT_RECOVERY` | 恢复 | Critical | +| `ALERT_DEGRADED_RECOVERY` | 恢复 | Warning | +| `ALERT_SSL` | 活动、单次事件 | Warning | +| `NO_ALERT` | 忽略，不创建事件 | - | + +空值或未知的 `alert_type` 会返回参数错误。恢复只根据 `alert_type` 判断，与标题或错误文本无关。 + +## 标签和描述 +--- + +Flashduty 会生成以下标签： + +- `check`、`source=checkly` +- `check_id`、`checkly_alert_type` +- `check_name`、`check_type`、`group_name` +- `region`、`run_location` +- `is_reminder`、`reminder_sequence` +- JSON 编码后的 `tags` + +`check_result_id` 是每次执行产生的高基数字段，不会写入标签。错误信息、响应状态、响应时间、开始时间和结果链接会进入有长度限制的告警描述。 + +## 投递和排查 +--- + +Checkly 对失败的 Webhook 投递最多重试 5 次，每次间隔约 20 秒。可在 Checkly 的 Alert Notification Log 中查看最终投递结果。 + +- **Flashduty 返回参数错误**：确认 Body 是有效 JSON，并使用上面的完整模板；检查 `alert_type` 是否为支持值 +- **同一个 Check 产生多条告警**：确认每次通知都带有相同且非空的 `check_id` +- **告警没有恢复**：确认 Notification events 已启用 Recovery，且恢复 Payload 的 `check_id` 与触发时一致 +- **没有降级告警**：确认已启用 Degradation，并为 Check 配置了降级条件 +- **没有收到通知**：确认目标 Check 或 Check Group 已订阅该 Webhook Channel，并在 Alert Notification Log 中检查投递状态 + +Checkly 的状态转换说明请参阅 [Alerting With Checkly](https://www.checklyhq.com/docs/alerting-and-retries/custom-alerts/)。