Alerts

当部署失败、运行中的服务停止或停止响应，或组织使用量超过套餐阈值时，Alerts 会通知你的团队。你在组织级别配置告警，然后选择每个告警覆盖哪些项目和环境。

组织管理员可以创建和管理告警。其他组织角色对告警设置拥有只读访问权限。

打开 Mastra platform 仪表盘，进入你的组织设置，然后选择 Alerts。该页面有三个标签页：

• Alerts 列出每个告警及其作用域、目的地、状态和启用或暂停开关。
• Destinations 列出可接收通知的 Slack 频道、Discord 频道、Microsoft Teams 频道、电子邮件组、webhook 端点、PagerDuty 服务和 incident.io 告警源。
• Activity 显示事件以及与之关联的通知尝试。

添加目的地

目的地定义 Mastra 将通知发送到哪里。在创建告警之前，请至少添加一个目的地。

目的地	配置
Slack	连接一个 Slack workspace 并选择一个或多个频道。Mastra 会为每个选中的频道创建一个单独的目的地。
Discord	输入 Discord 频道 webhook URL。参见向 Discord 发送告警。
Microsoft Teams	输入向频道发布消息的 Teams workflow URL。参见向 Microsoft Teams 发送告警。
Email	选择组织角色、单个成员或最多 10 个电子邮件地址。基于角色的收件人组会在组织成员变化时更新。
Webhook	输入 HTTPS 端点。Mastra 会为每个请求签名，并在目的地创建后一次性显示签名密钥。
PagerDuty	输入 PagerDuty Events API v2 集成的 integration key。参见向 PagerDuty 发送告警。
Incident.io	输入 incident.io HTTP 告警源的 alert source config ID 和 token。参见向 incident.io 发送告警。

1. 在 Destinations 标签页中，选择 Add destination。

2. 选择 Slack、Discord、Microsoft Teams、Email、Webhook、PagerDuty 或 Incident.io，然后为目的地输入名称。

3. 配置所选目的地：

   • 对于 Slack，连接或选择一个 workspace，并选择应接收告警的频道。Mastra Alerts 应用会自动加入公共频道。在选择私有频道之前，请邀请 @Mastra Alerts。
   • 对于 Discord，输入频道的 webhook URL。
   • 对于 Microsoft Teams，输入 workflow 的 webhook URL。
   • 对于电子邮件，选择 All organization members、一个或多个角色、单个成员或外部电子邮件地址。
   • 对于 webhook，输入以 https:// 开头的端点。
   • 对于 PagerDuty，输入 Integration key。
   • 对于 incident.io，输入 Alert source config ID 和 Token。

4. 选择 Create destination。对于 webhook 目的地，请在关闭页面前复制签名密钥。该密钥无法再次显示。

目的地表单会根据所选类型变化。Slack 目的地需要 workspace 和至少一个频道。Discord 和 Microsoft Teams 目的地需要 webhook URL。电子邮件目的地需要至少一个收件人，可以是组织角色、成员或外部地址。Webhook 目的地需要 HTTPS 端点。PagerDuty 和 incident.io 目的地需要来自其集成的凭据。每个目的地还需要一个名称，用于在告警配置和活动历史中标识它。

使用目的地的操作菜单发送测试通知。你还可以编辑、暂停或删除目的地。暂停目的地会停止通知，但不会将其从现有告警中移除。

对于 webhook 目的地，Rotate secret 会立即替换当前的签名密钥。在发送另一个告警之前，请使用新密钥更新接收端点。

Discord 和 Microsoft Teams webhook URL 自带凭据，因此 Mastra 会加密存储它们，并在目的地创建后仅显示最后四个字符。要轮换 URL，请编辑目的地并粘贴新的 URL。将 URL 字段留空会保留已存储的 URL。

创建告警

告警组合了触发器、作用域、目的地和重复告警节奏。

1. 在 Alerts 标签页中，选择 Create Alert。

2. 输入告警名称；如果告警应立即开始监控，请保持 Enabled 开启。

3. 选择一个或多个触发器：

   • Deploy failed：构建或部署未达到运行状态。
   • Service crashed：运行中的服务耗尽其重启策略并停止。
   • Service out of memory：服务在内存耗尽后被停止。
   • Service unreachable：已部署的服务连续 3 次健康检查失败。
   • Usage threshold crossed：组织使用量超过套餐阈值或达到其限制。此触发器是组织范围的，因此需要 All projects 作用域。

4. 将告警作用域设置为 All projects 或 Specific projects。当你选择特定项目时，可以将作用域缩小到单个环境。将环境选择留空会包含该项目的所有环境。

5. 选择一个或多个目的地。你可以在不离开告警设置的情况下添加或编辑目的地。

6. 在 Repeat alerts 下，选择 Mastra 可以为同一事件重新发送告警的频率：每次事件、每 5 分钟、每 15 分钟或每小时。首次通知、恢复通知和严重性升级会立即发送。

7. 选择 Create Alert。

告警表单将这些设置分为 Name、Trigger、Scope 和 Destinations。所选目的地和重复间隔适用于该告警中包含的每个触发器和项目。

管理告警

Alerts 标签页显示每个告警的作用域、目的地和当前状态。使用开关暂停或启用告警。

打开告警的操作菜单以：

• Edit 其触发器、作用域、目的地、节奏或名称。
• Test 分配给该告警的每个目的地。
• Delete 该告警。现有事件和投递历史仍然可用。

查看告警活动

Activity 标签页将每个事件与其投递尝试分组。条件处于活动状态时，事件保持 Open，并在服务或部署恢复后变为 Resolved；使用量阈值事件除外，它们不会自动解决。

展开事件以检查发送到每个目的地的通知。每个事件行显示事件发生的时间、事件类型、其项目或环境作用域，以及当前状态。嵌套的投递行显示每次通知尝试的触发器、目的地和投递状态。投递尝试可以是 Scheduled、Sent、Suppressed、Retrying、Exhausted 或 Config error。使用活动过滤器显示所有活动、仅事件或仅投递尝试。

向 Discord 发送告警

Discord 目的地通过 Discord webhook 向频道发布 embed。触发的事件会发布红色 embed，恢复则会单独发布一条绿色的 Resolved embed。Discord webhooks 无法更新之前的消息，因此恢复通知是一条新消息，而不是编辑。

1. 在 Discord 中，打开应接收告警的频道，然后依次选择 Edit Channel、Integrations、Webhooks 和 New Webhook。复制 webhook URL。参见 Discord 文档中的 Intro to Webhooks。

2. 在 Mastra 中，添加一个目的地，选择 Discord，然后将 URL 粘贴到 Webhook URL 中。URL 必须采用 https://discord.com/api/webhooks/<id>/<token> 形式。

3. 从目的地的操作菜单发送测试通知。

Embed 的标题中显示事件和项目，并链接到部署日志，随后是错误摘录；当事件包含环境、分支和错误代码时，也会显示这些信息。如果 Discord 拒绝该 webhook URL，投递状态会显示 Config error。

向 Microsoft Teams 发送告警

Microsoft Teams 目的地通过 Teams workflow 向频道发布 Adaptive Card。触发的事件会发布红色卡片，恢复则会单独发布一条绿色的 Resolved 卡片。

1. 在 Teams 中，打开应接收告警的频道，选择 More options，然后选择 Workflows，并选择模板 Send webhook alerts to a channel。选择团队和频道，创建工作流，然后复制 workflow URL。参见 Microsoft 文档中的 Create incoming webhooks with Workflows。

2. 在 Mastra 中，添加一个目的地，选择 Microsoft Teams，然后将 URL 粘贴到 Webhook URL 中。

3. 从目的地的操作菜单发送测试通知。

Microsoft 已停用经典的 Office 365 connectors，因此请使用 Teams workflow 而不是较旧的 Incoming Webhook connector。对于尚未迁移的租户，Mastra 仍接受旧版 webhook.office.com URL。

卡片的标题中显示事件和项目，随后是环境、分支和错误代码（当事件包含它们时）、错误摘录，以及一个打开部署日志的按钮。如果 Teams 拒绝该 workflow URL，投递状态会显示 Config error。

向 PagerDuty 发送告警

PagerDuty 目的地会向 PagerDuty Events API v2 发送事件。每个 Mastra 事件会打开一个 PagerDuty 事件，当 Mastra 事件解决时，PagerDuty 会将其解决。

1. 在 PagerDuty 中，打开应接收告警的服务。在其 Integrations 标签页中，添加 Events API V2 集成并复制其 Integration Key。参见 PagerDuty 文档中的 Services and integrations。

2. 在 Mastra 中，添加一个目的地，选择 PagerDuty，然后将密钥粘贴到 Integration key 中。

3. 从目的地的操作菜单发送测试通知。测试会在 PagerDuty 中打开一个 info 严重性的事件。请在 PagerDuty 中解决它。

Mastra 将其通知映射到 PagerDuty 事件，如下所示：

PagerDuty 字段	值
event_action	对于新通知或重复通知为 trigger，对于恢复为 resolve
dedup_key	Mastra 事件 ID。同一事件的重复通知会更新同一个 PagerDuty 事件
payload.summary	单行描述，例如 Deploy failed on support-agent (production): Build failed
payload.severity	Mastra 严重性：critical、error、warning 或 info
payload.source	mastra:<project>/<environment>
payload.custom_details	Webhook 载荷中描述的事件数据

在 PagerDuty 中所做的更改（例如确认或解决事件）不会更新 Mastra 事件。如果 PagerDuty 拒绝 integration key，投递状态会显示 Config error。

向 incident.io 发送告警

incident.io 目的地会向 incident.io HTTP 告警源发送告警事件。每个 Mastra 事件会在 incident.io 中创建一个告警，当 Mastra 事件解决时，该告警会解决。

1. 在 incident.io 中，创建一个 Default 源类型的 HTTP 告警源。Mastra 以 incident.io 告警事件格式发送事件，因此不需要自定义转换。参见 incident.io 文档中的 Create an alert event。

2. 从源的 authorization 头中复制 alert source config ID 和 bearer token。该 ID 是告警事件 URL https://api.incident.io/v2/alert_events/http/<alert-source-config-id> 的最后一段。

3. 在 Mastra 中，添加一个目的地并选择 Incident.io。将 ID 或完整的告警事件 URL 粘贴到 Alert source config ID 中，并将 token 粘贴到 Token 中。

4. 从目的地的操作菜单发送测试通知。测试会在 incident.io 中创建一个 firing 告警。

Mastra 向 incident.io 发送以下字段：

incident.io 字段	值
status	对于新通知或重复通知为 firing，对于恢复为 resolved
deduplication_key	Mastra 事件 ID
title	事件的一行描述
description	错误消息（当事件有时）
metadata	事件数据加上 source、event_type、severity、project_id 和 environment

在告警属性和路由规则中使用 metadata 字段。在 incident.io 中所做的更改不会更新 Mastra 事件；如果 incident.io 拒绝 token 或 alert source ID，投递状态会显示 Config error。

接收 webhook 通知

Webhook 目的地会为每个通知接收一个带有 JSON 体的 HTTP POST 请求。使用 webhook 连接 Mastra 未直接集成的工具。

Webhook 载荷

以下示例显示一次失败的部署：

{
  "id": "deploy.failed:dep_8c2f1a:triggered",
  "version": "2026-09-01",
  "type": "deploy.failed",
  "createdAt": "2026-09-24T14:03:11.000Z",
  "fingerprint": "deploy.failed|prj_41d9e2|server|production",
  "severity": "error",
  "status": "triggered",
  "summary": "Deploy failed on support-agent (production): Build failed",
  "source": "mastra",
  "data": {
    "deployId": "dep_8c2f1a",
    "projectName": "support-agent",
    "gitBranch": "main",
    "error": "Build failed",
    "errorCode": "BUILD_FAILED",
    "errorCategory": "build",
    "deployUrl": "https://projects.mastra.ai/..."
  },
  "links": []
}

字段	描述
id	通知 ID。当 Mastra 重试同一通知时保持不变
version	载荷版本。当前版本为 2026-09-01
type	事件类型。参见下表
createdAt	事件发生时的 ISO 8601 时间
fingerprint	标识该通知所属的事件。针对同一失败部署目标或服务的通知共享一个 fingerprint
severity	critical、error、warning 或 info。这些值与 PagerDuty 严重性匹配
status	对于新通知或重复通知为 triggered，当事件恢复时为 resolved
summary	事件的一行描述
source	始终为 mastra
data	事件特定的详情。字段因事件类型而异
links	相关链接，每个包含 href 和 text。可以为空

type 字段具有以下值之一：

类型	触发器	常见 data 字段
deploy.failed	Deploy failed	deployId、projectName、gitBranch、error、errorCode、errorCategory、deployUrl
service.crashed	Service crashed	与 deploy.failed 相同
service.oom	Service out of memory	与 deploy.failed 相同
service.unreachable	Service unreachable	projectName、probeUrl、error、consecutiveFailures
billing.usage_threshold	Usage threshold crossed	featureId、featureLabel、thresholdDisplay、error

同一服务的崩溃、内存耗尽和不可达事件共享一个 fingerprint，因此一次中断只会产生一个事件。使用量阈值事件不会发送 resolved 通知。

测试通知使用 type: "deploy.failed"、severity: "info"，并在 data 中包含 "test": true。

请求头

请求头	值
content-type	application/json
user-agent	Mastra-Alerts/1.0
x-mastra-signature	请求体的签名。参见验证 webhook 签名
x-mastra-idempotency-key	与载荷 id 相同的值

验证 webhook 签名

在信任请求之前先验证签名。x-mastra-signature 请求头具有以下格式：

t=1790258591,v1=5f0c9d3e...

t 是 Mastra 签署请求时的 Unix 时间（秒）。v1 是字符串 <t>.<raw request body> 的十六进制编码 HMAC-SHA256，使用目的地的签名密钥作为 key。

要验证请求：

1. 在将请求体解析为 JSON 之前读取原始请求体。再次解析和序列化请求体会改变它。
2. 计算 <t>.<raw body> 的 HMAC，并使用恒定时间比较将其与 v1 进行比较。
3. 拒绝 t 超过几分钟之前的请求，以防止重放请求。

Node.js

verify-mastra-signature.ts

import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_SECONDS = 300

export function verifyMastraSignature(
  rawBody: string,
  signatureHeader: string,
  signingSecret: string,
): boolean {
  const parts = new Map(signatureHeader.split(',').map(part => part.split('=') as [string, string]))
  const timestamp = Number(parts.get('t'))
  const signature = parts.get('v1')
  if (!Number.isInteger(timestamp) || !signature || !/^[0-9a-f]{64}$/.test(signature)) return false
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false

  const expected = createHmac('sha256', signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')
  const expectedBytes = Buffer.from(expected, 'hex')
  const signatureBytes = Buffer.from(signature, 'hex')
  return (
    expectedBytes.length === signatureBytes.length && timingSafeEqual(expectedBytes, signatureBytes)
  )
}

Python

verify_mastra_signature.py

import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_mastra_signature(raw_body: bytes, signature_header: str, signing_secret: str) -> bool:
    parts = dict(part.partition("=")[::2] for part in signature_header.split(","))
    try:
        timestamp = int(parts["t"])
        signature = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False

    expected = hmac.new(
        signing_secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

对于验证失败的请求，返回 401 状态。轮换目的地的密钥后，请求会立即使用新密钥签名。

重试和重复通知

Mastra 将任何 2xx 响应视为已投递，不会重试。在响应之前持久化或持久地排队该通知；如果该步骤失败，请返回 5xx 响应，以便 Mastra 重试投递。请在 10 秒内响应；如果处理时间更长，请在响应后处理通知。Mastra 不跟随重定向。

当请求失败时，Mastra 会根据响应进行重试：

• 4xx 响应： Mastra 停止并将投递标记为 Config error。修复端点，然后使用目的地的 Test 确认其正常工作。
• 5xx 响应、超时或网络错误： Mastra 会在几秒内重试两次。如果这些请求也失败，投递状态会显示 Retrying，Mastra 会在约 30 秒后再次尝试，每次将等待时间翻倍，最多 15 分钟。经过 6 次失败尝试后，投递状态会显示 Exhausted。

Discord、Microsoft Teams、PagerDuty 和 incident.io 目的地遵循相同的时间表。对于这些目的地，Mastra 还会重试 408 和 429 响应。

重试可能多次投递同一通知。存储每个已处理请求的 x-mastra-idempotency-key 值，并跳过已见过该 key 的请求。使用 fingerprint 对属于同一事件的通知进行分组。