- 変化イベントは、プロンプトの回答が変わったときに
webhookUrlへ送られます: 自社ブランドが現れた・消えた、競合が 前に出た、あるサイトが初めて引用された、などです。 - アラートは、直近7日間のブランドの言及率が
alertBelowPctを下回ったときに、アカウントの管理者にメールします。
変化イベント
モニターを作成または更新するときにwebhookUrl を設定します。
400 VALIDATION_ERROR を返します。webhookUrl: null でイベントを
止め、モニターのイベント状態を破棄します。再びオンにすると履歴から始まります。
イベントの種類
ブランドのイベントはプロンプトごとに、エンジンごとに、グリッドモニターでは地点ごとに別々に追跡します。状態は直近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 です。例:
署名と再試行
イベントはタスクのWebhookと同じように署名・再試行されます: 同じ3つのquerying-webhook-* ヘッダー、同じ HMAC-SHA256
方式、同じ再試行スケジュールです。Webhookのコードで検証してください。
異なる点は2つです。
querying-webhook-idはイベントのidです。これで重複を除いてください。- HMACキーは、タスクのキーではなく、
webhookUrlを設定したAPIキーの SHA-256 ダイジェストです。
webhookUrl を送り直すと、以後のイベントはそのキーで署名されます。
webhookUrl を設定したキーが失効または期限切れになるとイベントは止まります。各イベントは delivery.lastError に理由を
残して failed になり、署名なしで送られることはありません。
イベントの一覧と再送
GET /v1/monitors/{id}/events(リファレンス)はイベントを新しい順に
一覧します。
レスポンスは
webhookUrl、nextCursor(最後のページでは null)、events を持ちます。各イベントは id、type、
createdAt、data(ペイロードと同じ)、delivery を持ちます。
POST /v1/monitors/{id}/events/{eventId}/redeliver
(リファレンス)は、イベントを1件、現在の webhookUrl に今すぐ再送し、
再試行を最初から数え直して、更新された delivery 付きのイベントを返します。配信済みのイベントも再送できます。モニターに
webhookUrl がなければ 409 WEBHOOK_NOT_SET、不明なイベントには 404 NOT_FOUND を返します。
イベントは30日間保持されます。再試行中のイベントは再試行が終わるまで保持されます。
アラート
ブランドモニターにalertBelowPct(1〜100の整数のパーセント)を設定すると、ブランドの言及率がそれを下回ったときに
メールを受け取れます。
- 期間: モニターのすべてのプロンプトとエンジンにわたる、直近7日間の採点済み回答。レポートの 既定は30日ですが、それでは動きが遅すぎて警告になりません。
- タイミング: 定期実行が始まるたび。すでに採点された回答を読むため、前の実行までを反映します。
- 最小サンプル: 期間内の採点済み回答が5件未満なら発火しません。新しいモニターや、エンジンが失敗し続けている モニターは通知しません。
- 状態ではなく境界の通過: 言及率がしきい値を下回り、アラートが有効なときに発火し、その後無効になります。言及率が
しきい値以上に戻ると再び有効になるため、低いままのモニターは実行ごとではなく1回だけメールします。
alertBelowPctを 変更すると再び有効になります。
alertBelowPct を 400 VALIDATION_ERROR で拒否します。
alertBelowPct: null でアラートをオフにします。
アラートの履歴
GET /v1/monitors/{id}/alerts(リファレンス)は 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(リファレンス)は、実際のアラートと
同じ配信経路で、モニター名の後に「(test)」を付けたテストメールをキューに入れ、data.queued: true を返します。結果は
アラートの履歴で確認してください。テストメールはモニターごとに5分に3回まで送れ、超えると 429 RATE_LIMITED を
返します。カテゴリモニターは 400 VALIDATION_ERROR を返します。
次のステップ
Webhook
すべてのWebhookの署名、再試行、安全なハンドラー。
ソースと回答
イベントの裏にある回答を開きます。