> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger.dev 告警集成

> 通过 Webhook 告警渠道将 Trigger.dev 的任务运行失败、错误分组和部署失败事件同步到 Flashduty On-call。

通过 Trigger.dev 的 Webhook 告警渠道，将任务运行失败、错误分组和部署结果同步到 Flashduty On-call。Trigger.dev 云服务和自托管版本使用同一套告警渠道。

* **运行失败**（`alert.run.failed`）：任务重试耗尽后失败的每个运行对应一条告警。Trigger.dev 没有对应的恢复通知，因此告警不会自动恢复。请在协作空间中开启超时自动关闭，见下文 [运行失败和错误分组不会恢复](#运行失败和错误分组不会恢复)。
* **错误分组**（`alert.error`）：新错误出现、已解决的错误再次出现、被忽略的错误突破忽略条件时各推送一次，同样不会自动恢复。
* **部署失败 / 部署成功**（`alert.deployment.failed`、`alert.deployment.success`）：同一环境的部署失败后触发告警，该环境下一次部署成功时告警恢复。

<div className="hide">
  ## 在 Flashduty On-call

  ***

  您可通过以下两种方式获取集成推送地址，任选其一即可。

  ### 使用专属集成

  1. 进入 Flashduty 控制台，选择 **协作空间**，打开一个协作空间
  2. 选择 **配置** → **集成数据** → **专属集成**，点击 **新增一个集成**
  3. 选择 **Trigger.dev**，点击 **保存**
  4. 打开生成的集成卡片，复制 **推送地址**

  ### 使用共享集成

  1. 进入 Flashduty 控制台，选择 **集成中心 → 告警事件**
  2. 选择 **Trigger.dev**，填写集成名称
  3. 配置默认路由并选择协作空间；创建后可在 **路由** 中增加更多规则
  4. 点击 **保存**，复制生成的 **推送地址**
</div>

## 在 Trigger.dev 中配置

***

Webhook 渠道按项目和环境创建。云服务的免费套餐包含 1 个告警渠道（Webhook、邮件、Slack 合计），套餐用量用完后需要升级或删除已有渠道。

<Steps>
  <Step title="创建运行失败和部署告警">
    1. 进入 Trigger.dev 项目，切换到需要告警的环境（如 Production），点击左侧 **Alerts**，再点击 **New alert**
    2. **Alert method** 选择 **Webhook**
    3. 将 Flashduty 集成的完整推送地址粘贴到 **URL**，地址中需包含 `integration_key`
    4. 勾选需要的告警类型：**Task runs fail**、**Deployments fail**、**Deployments succeed**；不要勾选 **Dashboard agent watches**，该类型的事件不在本集成的处理范围内，类型无法识别的请求会被拒绝（HTTP 400）
    5. 点击保存

    Webhook 渠道只对创建它的环境生效。需要覆盖多个环境时，在每个环境中各创建一次。必须同时勾选 **Deployments fail** 和 **Deployments succeed**，否则部署失败的告警不会恢复。
  </Step>

  <Step title="创建错误分组告警（可选）">
    错误分组告警在 **Errors** 页面创建：点击 **Configure alerts…**，渠道选择 Webhook，粘贴同一个推送地址。创建后它会出现在 **Alerts** 列表中，类型为 Error group。
  </Step>

  <Step title="验证">
    Trigger.dev 的告警渠道没有测试按钮。触发一个会失败的任务运行（重试耗尽后才会推送），确认 Flashduty 收到告警；部署失败可以通过部署一个构建会失败的版本验证，再部署一个正常版本确认告警恢复。
  </Step>
</Steps>

Trigger.dev 会为每个 Webhook 渠道生成一个签名密钥，并在请求头 `x-trigger-signature-hmacsha256` 中携带签名。Flashduty 不校验该签名，访问凭据是推送地址中的 `integration_key`。

## 运行失败和错误分组不会恢复

***

这两类告警没有恢复通知。在接收该集成的协作空间中开启 [超时自动关闭](/zh/on-call/channel/create-edit)，建议运行失败 12 小时、错误分组 24 小时，并按团队处理失败任务的时效调整。每个失败的运行是一条独立告警；同一错误分组在被标记为已解决（或忽略条件被突破）后再次推送，会更新同一条告警，告警被关闭后再次推送则创建新的告警。

Trigger.dev 的错误分组告警只在状态变化时推送：处于 Unresolved 的分组不会重复推送。如果需要知道每一次运行失败，请使用运行失败告警。

## Alert Key

***

| 事件类型 | Alert Key |
| :- | :- |
| `alert.run.failed` | 运行 ID `object.run.id` |
| `alert.error` | 环境 ID `object.environment.id` + 错误指纹 `object.error.fingerprint` |
| `alert.deployment.failed` / `alert.deployment.success` | 环境 ID `object.environment.id` |

请求最外层的 `id` 是每次推送的投递 ID，不参与 Alert Key。部署的 `deployment.id` 每次部署都不同，所以失败与成功用环境区分：同一环境下，成功的部署恢复该环境的部署失败告警。标题、错误信息、发生次数、`classification` 的变化都不会改变 Alert Key。缺少上述字段的事件会被拒绝；`type` 不是上表中的取值时也会被拒绝。

## 状态和告警等级

***

| 事件类型 | 状态 | Flashduty 等级 |
| :- | :- | :- |
| `alert.run.failed` | 触发 | Critical |
| `alert.error` | 触发 | Critical |
| `alert.deployment.failed` | 触发 | Critical |
| `alert.deployment.success` | 恢复 | Info |

Trigger.dev 的告警不带严重级别，失败类事件统一按 Critical 处理。

## 标签

***

| 标签 | 来源 |
| :- | :- |
| `source` | 固定为 `trigger-dev` |
| `event_type` | 事件类型 |
| `check` / `task_id` | 任务标识 |
| `run_id` / `run_number` / `run_status` / `run_url` | 运行 ID、编号、状态、控制台链接 |
| `machine` / `tags` | 运行使用的机器规格、运行标签（排序后以逗号连接） |
| `file_path` / `task_version` | 任务所在文件、任务版本 |
| `deployment_id` / `deployment_status` / `version` / `short_code` | 部署信息 |
| `git_branch` / `git_commit` | 部署关联的 Git 分支和提交 |
| `classification` / `fingerprint` / `error_type` / `occurrences` / `dashboard_url` | 错误分组信息 |
| `env` / `env_id` / `environment_type` / `branch` | 环境标识（slug，为空时取环境名称）、ID、类型和预览分支 |
| `organization` / `project` / `project_ref` | 组织名称、项目名称和引用 |

## 排查问题

***

* **Flashduty 没有收到事件**：运行失败告警要等任务重试耗尽后才推送；确认渠道创建在发生失败的环境中，并勾选了对应的告警类型。Trigger.dev 要求 Webhook 地址为公网可访问的地址
* **Flashduty 返回参数错误**：确认请求体包含 `type` 和 `object` 字段（实际推送中运行和部署事件的 `webhookVersion` 为 `v1`，错误分组事件为 `2025-01-01`），并且勾选的是上述支持的告警类型。旧版 Webhook 渠道的请求体没有 `type` 和 `object` 字段，不被支持，请删除后重新创建渠道
* **部署失败告警没有恢复**：确认该环境的渠道同时勾选了 **Deployments succeed**，并且恢复的是同一环境的部署
* **Trigger.dev 提示套餐告警渠道已用完**：删除不用的渠道，或升级套餐

更多字段含义请参阅 [Trigger.dev Alerts](https://trigger.dev/docs/troubleshooting-alerts)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.