通知 API

プロジェクトを対象にする組織の通知（すべてのチャネル）を古い順に一覧表示します（最大50件）。status、failing_since、last_success_at、last_failure_at はこのプロジェクトの値です。Webhook の署名シークレットはここでは返されません。

プロジェクト権限が必要です。レポート専用の認証情報は、レスポンスに受信先 URL と受信者が含まれるため、403 forbidden で拒否されます。

通知を作成します。channel email は recipients（オーナー、またはプロジェクトメンバーの user_ids）に送信します。channel webhook は url に署名付きで POST し、url は Webhook URL のルールに従います（パブリックインターネットホストの https、ポート 443 または 8443。それ以外は webhook_url_rejected）。conditions は通知が発火するスクリーンの状態変化を列挙します。メール通知には少なくとも1つ、Webhook には conditions または event_types が必要です。screen_tags は conditions を、いずれかのタグを持つスクリーンに限定します。空の場合はすべてのスクリーンが対象で、audience はキャンペーンのオーディエンスのルールでどのスクリーンかを指定します。min_severity と severity は通知を絞り込み、重大度を付与し、active_hours はそのウィンドウ外の通知を保留または破棄します。

条件は、hold_minutes（デフォルトは 10）の間継続した後にのみ通知されます。通知の送信後に条件が解消すると、続いて解決の通知が送信されます。この通知の対象はこのプロジェクトのみです。組織に作成できる通知は、システムが作成するデフォルトの通知を除いて最大50件です（notification_limit_reached）。

Webhook の署名シークレットはサーバーが生成し、この応答と rotate-secret でのみ返されます。保管してください。同じ Idempotency-Key を付けた同一内容の再試行には、シークレットを含む同じ応答が24時間返されます。通知は notification.created の後の最初のイベントから始まります。

プロジェクト権限が必要です。レポート専用の認証情報は、レスポンスに受信先 URL または受信者が含まれるため、403 forbidden で拒否されます。

description（空にするとクリア）、conditions、screen_tags、audience、min_severity、severity、active_hours（これらは null でそれぞれクリア）、hold_minutes、recipients（メール）、url と event_types（Webhook）、destination と telegram_chat_id（Slack、Teams、PagerDuty、Telegram）、enabled、snoozed_until のいずれかを変更します。channel は変更されません。

もう一方のチャネルのフィールドは invalid_request です。新しい url は作成時と同様に検証されます。

無効な通知で enabled を true にすると、失敗状態がクリアされ、その変更を記録したイベントから開始します。無効だった間のものは何も送信されず、無効化の前から送信待ちだった通知は webhook_disabled で失敗として扱われます。snoozed_until を指定すると、その時刻まで何も送信されません（最大30日先まで。null でスヌーズが終了します）。その間に送信時刻を迎えた通知はスキップされます（snoozed）。

notification.updated を追加します。If-Match がリビジョンを保護します。ここで変更できるのは、このプロジェクトだけを対象にする通知です。組織の他のプロジェクトも対象にする通知は notification_covers_other_projects となり、組織の「通知」ページから変更します。

通知を削除し、notification.deleted を追加します。送信待ちの通知は webhook_deleted で失敗として扱われ、配信ログは参照できなくなり、イベント保持期間に合わせて期限切れになります。ここで削除できるのは、このプロジェクトだけを対象にする通知です（そうでない場合は notification_covers_other_projects）。

Webhook 通知のみです（それ以外のチャネルは invalid_request になります）。署名シークレットを置き換え、新しいシークレットを secret に含めた通知を返します。古いシークレットは直ちに署名に使われなくなりますが、すでに送信中の試行が最大1件、古いシークレットで署名されたまま届くことがあるため、しばらくは両方を受け付けてください。notification.updated を details.changed [secret] とともに追加します。

完全一致する Idempotency-Key の正確な再試行は24時間同じ新しいシークレットを返します。

notification.test プロジェクトイベントを追加し、この通知のみに、そのイベントの配信を1件キューに入れます（他の通知が notification.test を受け取ることはありません）。

Webhook にはイベントがボディとして送られ、メール通知では受信者にテストメールが送信されます。Slack、Teams、Telegram の通知はテストメッセージを投稿し、PagerDuty の通知は情報イベントを発生させて直ちに解決します。

無効な通知やスヌーズ中の通知でも動作し、再試行なしで1回だけ試行され、通知の失敗状態は変更されません。結果は配信ログをポーリングして確認してください。

通知の配信ログです。新しいイベントが先頭に並びます。行はイベントごとに1つで、スクリーンの通知ではそのイベントの条件ごとに1つです。再試行では行が更新され、GET .../deliveries/{delivery_id}/attempts でその直近の試行を一覧表示できます。送信する必要がなかった通知は、その理由とともにスキップされます。

行はイベントと同様に保持されます（プランのイベント保持期間で、少なくとも24時間の再試行期間）。次のページを取得するには、これまでと同様に next_cursor を渡します。

1つの配信の試行を、新しい順に直近20件まで返します。配信の行と同じ期間、保持されます。各試行には、試行番号、完了した時刻、受信側の HTTP ステータス（応答がなかった場合とメールの場合は null）、エラークラス（成功時は null）、所要時間が含まれます。

この通知のものではない配信、または別のプロジェクトの通知は not_found になります。

メール内の配信停止リンクで通知のメールを止めた人に、再びメールを送ります (Notification.unsubscribed に該当者が一覧されます)。冪等です。止めていない人を指定しても何も変わらず、応答は現状のままの通知です。

変更するとリビジョンが上がり、change は resubscribed、user_id、via は api の詳細とともに notification.updated が追加されます。ダッシュボードのセッションはプロジェクトの誰でも再購読でき、エージェントの認証情報にはプロジェクトの書き込み権限が必要です。本人が戻る方法は、配信停止リンクが返すページの Resubscribe ボタンです。

アラートメールのフッターにあるリンクです。セッションもベアラーも持たず、screenRIG が通知 n と人 u のために作成したトークン t がすべての権限となります。期限はなく、トークンが示す発行キーのバージョンが保持されている間は有効です。

応答は、その通知のメールをその人に対して止めるかどうかを尋ねるページで、何も変更しません。そのため、リンクを開くメールスキャナーが何かを止めることはありません。ボタンはこのパスに送信します。すでに止めている人には、ボタンで再購読できるページが表示されます。

一致しないトークン、通知、人、および削除された通知やメール通知ではない通知には、同じ 404 ページが返ります。ページにスクリプトはなく、送信先はこのオリジンだけです。1 アドレスあたり 1 分に最大 30 リクエストです (rate_limited)。

リンクの宛先の人に対する、通知のメールを止めます。クエリは GET リンクのものと同じで、本文は読み取らないため、メールプロバイダーの RFC 8058 ワンクリックリクエスト (すべてのアラートメールとテストメールにある List-Unsubscribe と List-Unsubscribe-Post ヘッダーに基づく List-Unsubscribe=One-Click) も、ページのボタンも、どちらも機能します。

止まるのはその人だけで、この通知についてだけです。ほかの人にはメールが届き続け、その人は受信者 (recipients) に残ります。冪等です。初回はリビジョンが上がり、change は unsubscribed、user_id、via は email_link の詳細とともに notification.updated が追加されます。

応答するページには Resubscribe ボタン (POST /api/notifications/resubscribe) があり、プロジェクトのメンバーは Notification.unsubscribed で止めている人を確認できます。メールを送る相手が残らない場合、通知は no_recipients としてスキップされます。一致しないリンクには GET と同じ 404 ページが返ります。1 アドレスあたり 1 分に最大 30 リクエストです (rate_limited)。

リンクの対象の人について POST /api/notifications/unsubscribe を取り消します。応答するページの Resubscribe ボタンです。リンク、権限、404 ページは同じで、冪等です。変更するとリビジョンが上がり、change は resubscribed、user_id、via は email_link の詳細とともに notification.updated が追加されます。1 アドレスあたり 1 分に最大 30 リクエストです (rate_limited)。