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

# 监测器事件与提醒：Webhook 与邮件通知

> 监测器的回答发生变化时接收签名的 Webhook，提及率低于阈值时接收邮件。

监测器可以在情况变化时通知你，你不必轮询它的报告：

* **变化事件**：提示词的回答发生变化时发送到你的 `webhookUrl`：你的品牌出现或消失、竞争对手领先，或某个网站首次被引用。
* **提醒**：品牌最近七天的提及率低于 `alertBelowPct` 时，给账户管理员发送邮件。

## 变化事件

在[创建](/zh/monitors.md#创建监测器)或更新监测器时设置 `webhookUrl`：

```bash theme={"theme":"css-variables"}
curl -X PATCH https://api.querying.ai/v1/monitors/$MONITOR_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://hooks.example.com/querying/monitors" }'
```

该 URL 必须是公网主机上的 HTTPS 地址。请用 API 密钥设置：事件使用设置它的密钥签名，因此没有密钥的请求（控制台会话）返回 `400 VALIDATION_ERROR`。
`webhookUrl: null` 关闭事件并丢弃监测器的事件状态；再次开启时会从其历史重新开始。

### 事件类型

| 事件 | 发送时机 |
| - | - |
| `monitor.mention.started` | 你的品牌在某个提示词最近五个回答中至少出现在三个中，而之前少于三个。 |
| `monitor.mention.stopped` | 你的品牌在某个提示词最近五个回答中降到两个或更少。 |
| `monitor.competitor.ahead` | 某个竞争对手在某个提示词最近五个回答中至少出现在三个中，且多于你的品牌。 |
| `monitor.source.first_cited` | 某个回答引用了监测器的回答此前从未引用过的域名。 |

品牌事件按引擎分别跟踪每个提示词，网格监测器还按每个点分别跟踪。状态从最近五个回答读取，因此设置 `samples: 5` 时一次运行即可得到完整状态。

* 事件在状态变化时发送一次。品牌持续不出现在回答中时，只发送一次 `monitor.mention.stopped`，直到它回来之前不再发送。
* 提示词积累五个回答后才有状态。第一个状态作为基准，不发送任何事件。
* 品类监测器没有自己的品牌，只发送 `monitor.source.first_cited`。

事件何时开始：

* **为已有回答的监测器开启 `webhookUrl`**：每个提示词的状态根据过去 30 天内最近五个回答重建，所有已被引用的域名都视为已知。事件从下一个回答开始。
* **创建时就设置 `webhookUrl`，或在还没有任何回答时开启**：首次运行确定已知域名，`monitor.source.first_cited` 统计该运行全部提交之后创建的任务的回答。
  品牌事件在提示词积累五个回答后开始。

### 负载

每个事件都是带 JSON 正文的 `POST` 请求。例如：

```json theme={"theme":"css-variables"}
{
  "event": "monitor.mention.stopped",
  "id": "fd61d8f6-ebdf-4162-8b55-fd052c8502a9",
  "createdAt": "2026-10-10T03:12:44.120Z",
  "monitor": { "id": "d39b8de0-b159-4229-bf58-7064e5369db1", "name": "Earbud brand tracking" },
  "data": {
    "engine": "CHATGPT",
    "prompt": "best wireless earbuds for commuting",
    "location": null,
    "taskId": "863edb44-fc62-40dd-a5be-2af9409d59b6",
    "answers": 5,
    "mentions": 2
  }
}
```

| 字段 | 含义 |
| - | - |
| `event` | 事件类型。 |
| `id` | 事件 id，同时作为 `querying-webhook-id` 请求头发送。请按它去重。 |
| `monitor` | 监测器的 `id` 和 `name`。 |
| `data.engine`、`data.prompt` | 回答所属的引擎和提示词。 |
| `data.location` | 回答所在点的 `{ latitude, longitude }`，没有地点时为 `null`。 |
| `data.taskId` | 触发事件的回答。用 [`GET /v1/monitors/{id}/answers/{taskId}`](/zh/monitors/evidence#读取单个回答) 打开。 |
| `data.answers`、`data.mentions` | 状态中的回答数（5）以及其中提到你的品牌的数量。仅限提及事件和竞争对手事件。 |
| `data.competitor`、`data.competitorMentions` | 竞争对手以及提到它的回答数。仅限 `monitor.competitor.ahead`。 |
| `data.domain`、`data.url`、`data.label` | 新被引用的域名、被引用的页面及其标签。仅限 `monitor.source.first_cited`，替代计数字段。 |

### 签名与重试

事件的签名和重试方式与任务 Webhook 相同：同样的三个 `querying-webhook-*` 请求头、同样的 HMAC-SHA256 方案和同样的重试计划。
用 [Webhook](/zh/concepts/webhooks.md#验证签名) 中的代码验证。有两点不同：

* `querying-webhook-id` 是事件的 `id`。请按它去重。
* HMAC 密钥是设置 `webhookUrl` 的 API 密钥的 SHA-256 摘要，而不是任务密钥的摘要。

轮换密钥后，用新密钥再次发送 `webhookUrl`，之后的事件就用新密钥签名。如果设置 `webhookUrl` 的密钥被吊销或过期，事件会停止：
每个事件都被标记为 `failed`，原因记录在 `delivery.lastError` 中，不会发送未签名的事件。

### 列出和重新投递事件

`GET /v1/monitors/{id}/events`（[参考](/zh/api-reference/monitors/list-events.md)）按从新到旧列出事件。

| 参数 | 说明 |
| - | - |
| `limit` | 1–100，默认 50。 |
| `type` | 一种事件类型。 |
| `cursor` | 上一页的 `nextCursor`。 |

响应包含 `webhookUrl`、`nextCursor`（最后一页为 `null`）和 `events`。每个事件带有 `id`、
`type`、`createdAt`、`data`（与负载中相同）和 `delivery`：

| 字段 | 含义 |
| - | - |
| `delivery.status` | `pending`（等待首次尝试或重试）、`delivered` 或 `failed`（重试已用尽，或无法投递）。 |
| `delivery.attempts` | 已尝试的次数。 |
| `delivery.deliveredAt` | 收到 `2xx` 的时间，或 `null`。 |
| `delivery.lastError` | 最近一次失败，例如 `HTTP 500`，或 `null`。 |

`POST /v1/monitors/{id}/events/{eventId}/redeliver`
（[参考](/zh/api-reference/monitors/redeliver-event.md)）立即把一个事件重新发送到当前的 `webhookUrl`，重新开始一轮重试，
并返回带有更新后 `delivery` 的事件。已投递的事件也可以再次发送。监测器没有 `webhookUrl` 时返回 `409 WEBHOOK_NOT_SET`，
未知事件返回 `404 NOT_FOUND`。

事件保留 30 天。仍在重试中的事件会保留到重试结束。

## 提醒

在品牌监测器上设置 `alertBelowPct`（1 到 100 的整数百分比），品牌提及率低于该值时你会收到邮件：

```bash theme={"theme":"css-variables"}
curl -X PATCH https://api.querying.ai/v1/monitors/$MONITOR_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "alertBelowPct": 40 }'
```

提醒的判定方式：

* **窗口**：最近 7 天的已评分回答，涵盖监测器的所有提示词和引擎。[报告](/zh/monitors/reports.md)默认 30 天，变化太慢，无法及时预警。
* **时机**：每次计划运行开始时。检查读取的是已评分的回答，因此反映的是之前的运行。
* **最小样本**：窗口内已评分回答少于 5 个时永不触发。新监测器或引擎持续失败的监测器不会发出提醒。
* **按越线而非状态**：比率低于阈值且提醒处于启用状态时触发，随后解除启用。比率回到阈值或以上后才重新启用，
  因此一直偏低的监测器只发一封邮件，而不是每次运行都发。修改 `alertBelowPct` 会重新启用提醒。

邮件发送给为该监测器付费的账户（子账户则为其母账户）的每位管理员。邮件写明四舍五入后的比率、阈值、窗口和已评分回答数，
并附有控制台中该监测器的链接。

品类监测器没有品牌比率，因此传入 `alertBelowPct` 会以 `400 VALIDATION_ERROR` 被拒绝。`alertBelowPct: null` 关闭提醒。

### 提醒历史

`GET /v1/monitors/{id}/alerts`（[参考](/zh/api-reference/monitors/get-alerts.md)）返回
`alertBelowPct`、`armed` 和 `deliveries`：该监测器最近 20 封提醒邮件，包括测试邮件。每次投递带有 `id`、`status`（`pending`、`sent` 或 `failed`）、
`attempts`、`createdAt`、`sentAt`、`lastError` 和 `payload`（`monitorId`、`name`、`ratePct`、`threshold`、`windowDays`、`runs`）。
投递记录保留 90 天。

### 发送测试提醒

`POST /v1/monitors/{id}/alerts/test`（[参考](/zh/api-reference/monitors/test-alert.md)）通过与真实提醒相同的投递路径排入一封测试邮件，
监测器名称后附有 “(test)”，并返回 `data.queued: true`。请在提醒历史中查看结果。每个监测器每五分钟可发送三封测试邮件；超出返回
`429 RATE_LIMITED`。品类监测器返回 `400 VALIDATION_ERROR`。

## 后续步骤

> **[Webhook](/zh/concepts/webhooks.md)**
>
> 所有 Webhook 的签名、重试和安全的处理程序。

> **[来源与回答](/zh/monitors/evidence.md)**
>
> 打开事件背后的回答。


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