> ## 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` へ送られます: 自社ブランドが現れた・消えた、競合が
  前に出た、あるサイトが初めて引用された、などです。
* **アラート**は、直近7日間のブランドの言及率が `alertBelowPct` を下回ったときに、アカウントの管理者にメールします。

## 変化イベント

モニターを[作成](/ja/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` | プロンプトの直近5件の回答のうち3件以上に自社ブランドが登場します。直前はそれ未満でした。 |
| `monitor.mention.stopped` | プロンプトの直近5件の回答で自社ブランドの登場が2件以下に下がります。 |
| `monitor.competitor.ahead` | 競合がプロンプトの直近5件の回答のうち3件以上に登場し、自社ブランドより多くの回答に登場します。 |
| `monitor.source.first_cited` | モニターの回答が一度も引用していないドメインを回答が引用します。 |

ブランドのイベントはプロンプトごとに、エンジンごとに、グリッドモニターでは地点ごとに別々に追跡します。状態は直近5件の
回答から読むため、`samples: 5` なら1回の実行で状態がそろいます。

* イベントは状態が変わったときに1回送ります。回答に登場しないままのブランドは `monitor.mention.stopped` を1回送り、
  戻るまで何も送りません。
* プロンプトは回答が5件たまると状態を持ちます。その最初の状態が基準となり、何も送りません。
* カテゴリモニターは自社ブランドを持たないため、`monitor.source.first_cited` だけを送ります。

イベントが始まる時点:

* **すでに回答があるモニターで `webhookUrl` をオンにする場合**: 各プロンプトの状態を直近30日間の最新5件の回答から
  再構成し、すでに引用されたドメインはすべて既知として扱います。イベントは次の回答から始まります。
* **`webhookUrl` 付きでモニターを作成する、または回答がまだない状態でオンにする場合**: 最初の実行で既知のドメインを
  決め、`monitor.source.first_cited` はその実行がすべて投入された後に作成されたタスクの回答から数えます。ブランドの
  イベントは、プロンプトの回答が5件たまってから始まります。

### ペイロード

各イベントは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}`](/ja/monitors/evidence#回答を1件読む)で開きます。 |
| `data.answers`、`data.mentions` | 状態に含まれる回答(5)と、そのうち自社ブランドを挙げた数。言及と競合のイベントのみ。 |
| `data.competitor`、`data.competitorMentions` | 競合と、それを挙げた回答の数。`monitor.competitor.ahead` のみ。 |
| `data.domain`、`data.url`、`data.label` | 新たに引用されたドメイン、引用されたページとそのラベル。`monitor.source.first_cited` のみで、件数の代わりに含まれます。 |

### 署名と再試行

イベントはタスクのWebhookと同じように署名・再試行されます: 同じ3つの `querying-webhook-*` ヘッダー、同じ HMAC-SHA256
方式、同じ再試行スケジュールです。[Webhook](/ja/concepts/webhooks.md#署名を検証する)のコードで検証してください。
異なる点は2つです。

* `querying-webhook-id` はイベントの `id` です。これで重複を除いてください。
* HMACキーは、タスクのキーではなく、`webhookUrl` を設定したAPIキーの SHA-256 ダイジェストです。

キーをローテーションした後、新しいキーで `webhookUrl` を送り直すと、以後のイベントはそのキーで署名されます。
`webhookUrl` を設定したキーが失効または期限切れになるとイベントは止まります。各イベントは `delivery.lastError` に理由を
残して `failed` になり、署名なしで送られることはありません。

### イベントの一覧と再送

`GET /v1/monitors/{id}/events`([リファレンス](/ja/api-reference/monitors/list-events.md))はイベントを新しい順に
一覧します。

| パラメーター | 説明 |
| - | - |
| `limit` | 1〜100、既定50。 |
| `type` | 1つのイベントの種類。 |
| `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`
([リファレンス](/ja/api-reference/monitors/redeliver-event.md))は、イベントを1件、現在の `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日間の採点済み回答。[レポート](/ja/monitors/reports.md)の
  既定は30日ですが、それでは動きが遅すぎて警告になりません。
* **タイミング**: 定期実行が始まるたび。すでに採点された回答を読むため、前の実行までを反映します。
* **最小サンプル**: 期間内の採点済み回答が5件未満なら発火しません。新しいモニターや、エンジンが失敗し続けている
  モニターは通知しません。
* **状態ではなく境界の通過**: 言及率がしきい値を下回り、アラートが有効なときに発火し、その後無効になります。言及率が
  しきい値以上に戻ると再び有効になるため、低いままのモニターは実行ごとではなく1回だけメールします。`alertBelowPct` を
  変更すると再び有効になります。

メールは、モニターの料金を支払うアカウント(サブアカウントの場合は親アカウント)のすべての管理者に届きます。四捨五入した
言及率、しきい値、期間、採点済み回答の数を記載し、ダッシュボードのモニターへのリンクを含みます。

カテゴリモニターにはブランドの言及率がないため、`alertBelowPct` を `400 VALIDATION_ERROR` で拒否します。
`alertBelowPct: null` でアラートをオフにします。

### アラートの履歴

`GET /v1/monitors/{id}/alerts`([リファレンス](/ja/api-reference/monitors/get-alerts.md))は `alertBelowPct`、`armed`、
`deliveries` を返します。`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`([リファレンス](/ja/api-reference/monitors/test-alert.md))は、実際のアラートと
同じ配信経路で、モニター名の後に「(test)」を付けたテストメールをキューに入れ、`data.queued: true` を返します。結果は
アラートの履歴で確認してください。テストメールはモニターごとに5分に3回まで送れ、超えると `429 RATE_LIMITED` を
返します。カテゴリモニターは `400 VALIDATION_ERROR` を返します。

## 次のステップ

> **[Webhook](/ja/concepts/webhooks.md)**
>
> すべてのWebhookの署名、再試行、安全なハンドラー。

> **[ソースと回答](/ja/monitors/evidence.md)**
>
> イベントの裏にある回答を開きます。


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