通知 API

按从旧到新的顺序列出覆盖该项目的组织通知，涵盖所有渠道（最多 50 个）。status、failing_since、last_success_at 和 last_failure_at 是此项目自己的值。此处绝不会返回 Webhook 的签名密钥。

需要项目权限；仅有报告权限的凭据会被拒绝并返回 403 forbidden，因为响应包含接收方 URL 和收件人。

创建通知。channel email 发送给 recipients（owner，或项目成员的 user_ids）；channel webhook 以签名方式 POST 到 url，url 遵循 webhook URL 规则（公共互联网主机上的 https，端口 443 或 8443，否则 webhook_url_rejected）。conditions 列出其触发的屏幕状态变化；电子邮件通知至少需要一个，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 之后的第一个事件开始发送。

需要项目权限；仅有报告权限的凭据会被拒绝并返回 403 forbidden，因为响应包含接收方 URL 或收件人。

更改 description（空值将其清除）、conditions、screen_tags、audience、min_severity、severity、active_hours（null 清除其中每一项）、hold_minutes、recipients（email）、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 中；旧密钥会立即停止用于签名，而最多有一次已在传输中的尝试仍可能以旧密钥签名送达，因此请短时间内同时接受新旧两个密钥。追加 notification.updated，details.changed 为 [secret]。

携带相同 Idempotency-Key 的精确重试在 24 小时内返回相同的新密钥。

追加一个 notification.test 项目事件，并仅为此通知排入一次该事件的投递（其他通知不会收到 notification.test）。

Webhook 会将该事件作为请求体收到；电子邮件通知会向其收件人发送一封测试电子邮件；Slack、Teams 或 Telegram 通知会发布一条测试消息；PagerDuty 通知会触发一个信息事件并立即将其解决。

它对已禁用或已暂停的通知同样有效，仅尝试一次且不重试，并且绝不改变该通知的失败状态。请轮询投递日志查看其结果。

该通知的投递日志，按事件从新到旧排列。每个事件一行；对于屏幕提醒，则每个事件的每个条件一行；重试会更新该行，GET .../deliveries/{delivery_id}/attempts 会列出其最近的尝试。无需发送的提醒会被跳过，并附上原因。

记录的保留方式与事件相同（按套餐的事件保留期，且不短于 24 小时的重试窗口）。与之前一样，将 next_cursor 传回即可获取下一页。

单次投递的尝试记录，按最新在前排列，保留最近 20 条，与投递记录一同保留，保留时长也相同。每条记录包含尝试序号、完成时间、接收方的 HTTP 状态（无响应或为电子邮件时为 null）、错误类别（成功时为 null）及其耗时。

不属于此通知的投递，或其他项目的通知，均会返回 not_found。

让已通过邮件中的取消订阅链接停止某个通知邮件的人重新收到邮件（Notification.unsubscribed 列出这些人）。幂等：未被停止的人不会带来任何变化，响应就是该通知当前的样子。

变更会提高修订号，并追加 notification.updated，其详情为 change resubscribed、user_id 和 via api。控制台会话可重新订阅项目中的任何人；智能体凭据需要项目写入能力。本人自行恢复的方式，是其取消订阅链接所返回页面上的 Resubscribe 按钮。

告警邮件页脚中的链接。它不带会话，也不带 bearer；由 screenRIG 为通知 n 和某人 u 生成的令牌 t 就是全部授权，永不过期，只要它所指的签发密钥版本仍被保留即有效。

响应是一个询问是否对此人停止该通知邮件的页面，不会改变任何内容，因此打开链接的邮件扫描器不会停止任何东西；页面按钮会提交到此路径。已被停止的人看到的页面，其按钮用于重新订阅。

任何不匹配的令牌、通知或人员，以及已被删除或不是电子邮件的通知，都会得到同一个 404 页面。该页面没有脚本，只向此源站提交。每个地址每分钟最多 30 个请求 (rate_limited)。

对链接所指的人停止某个通知的邮件。查询与 GET 链接相同；不读取请求体，因此邮件服务商的 RFC 8058 一键请求（List-Unsubscribe=One-Click，来自每封告警邮件和测试邮件所带的 List-Unsubscribe 与 List-Unsubscribe-Post 标头）和页面上的按钮都能使用。

只会停止这一个人，且仅限该通知；其他人继续收到邮件，此人仍留在收件人 (recipients) 中。该调用是幂等的。首次调用会提高修订号，并追加 notification.updated，其详情为 change unsubscribed、user_id 和 via email_link。

它返回的页面带有 Resubscribe 按钮 (POST /api/notifications/resubscribe)；项目成员可在 Notification.unsubscribed 中看到被停止的人。没有人可发邮件时，通知会以 no_recipients 跳过。任何不匹配的链接都会得到 GET 所返回的 404 页面。每个地址每分钟最多 30 个请求 (rate_limited)。

对链接所指之人撤销 POST /api/notifications/unsubscribe：即其所返回页面的 Resubscribe 按钮。链接、授权和 404 页面都相同；幂等。变更会提高修订号，并追加 notification.updated，其详情为 change resubscribed、user_id 和 via email_link。每个地址每分钟最多 30 个请求 (rate_limited)。