警报触发器 API

按从旧到新的顺序列出项目的触发器（CAP 和叠加层，最多 20 个），每个都带有其接收 url、username 以及最新的告警或叠加层状态。此处从不返回任何密钥。

创建一个 CAP 警报触发器：一个入站 URL，紧急通知系统（Everbridge、Rave、Alertus、IPAWS 中继及其他 CAP 1.2 发送者）通过 HTTP Basic 凭据向其发布警报。

答案是密码出现的唯一位置（带旋转答案）：请立即将其存储在发送系统中。target 是一个标签（警报到达时所有带该标签的活动屏幕）或最多 500 个 screen_ids。

警报会接管所有带默认播放列表的目标屏幕，直到警报的 <expires>，否则为 default_for_seconds（60 到 604800，默认 3600）；参见 POST /api/triggers/{id}/cap.。组织跨其所有项目最多有 20 个触发器（trigger_limit_reached）。追加 trigger.created。

携带相同 Idempotency-Key 的精确重试在 24 小时内返回相同答案，包括密码。

可选的 pull 会添加平台为该触发器读取的 CAP 来源（参见 CapPull）；接收 url 仍可同时使用。kind overlay 则创建第二种类型: 一个接收 url（POST /api/triggers/{id}/overlay），任何系统（Home Assistant、摄像头、告警工具）都可以向它推送几句话，告警持续期间会在目标屏幕上显示为正在播放内容之上的横条（overlay.show bar，位于底部或顶部）或接管（overlay.show takeover）；参见 TriggerOverlay。

signing 为 true 时，响应还会一次性带有签名密钥。verify 让服务商自己的签名（GitHub、Stripe、Shopify、Slack、Linear、Vercel、Asana 或任何 HMAC 发送方）代替密码来验证一个请求，密码仍可并行使用；它不能与 signing 同时使用，其密钥加密封存，绝不会返回，只返回一个提示。handshake 指定 URL 所响应的服务商握手（Microsoft Graph、monday.com、Trello 或 Azure Event Grid；verify slack 和 asana 会响应它们自己的握手）。

叠加层保持时长为 10 至 604800 秒（默认 600）。选择器涉及受保护屏幕的触发器为 protected_target（409），读取屏幕保护状态失败为 dependency_unavailable（500，重试同一请求）；限定屏幕范围的调用方无法使用触发器。

带有其最新告警的触发器；对于叠加层触发器，则是其有效告警（最新的在前，第一条正在显示）、分发计数以及是否有待处理的工作。超过 until 的告警读作已结束，ended_reason 为 expired。

更改触发器，而不更改其 URL 或密钥: label、target、default_for_seconds、CAP 触发器的 pull（null 将其移除），以及叠加层触发器的 overlay.edge、style（替换整个样式；null 将其清除）、mapping（null 将其移除）、enabled、signing、verify（null 将其移除；不带密钥时，若服务商相同则保留已存储的密钥）和 handshake（null 将其移除）。

已停用的叠加层触发器对其发送方返回与错误密钥相同的 404。开启签名会在这次答复中返回一次签名密钥。横条会在新的目标屏幕和新的边上重新放置；接管触发器的新目标从下一条开始的告警起生效。追加 trigger.updated，带有 details.changed。If-Match 用于保护修订。

每次更新都会针对触发器将拥有的目标进行检查，即新目标，否则为已存储的目标：无论哪位成员更改，涉及受保护屏幕的目标都是 protected_target（409）；读取屏幕保护状态失败为 dependency_unavailable（500，重试同一请求）。

删除触发器。其 URL 立即失效，其告警播放列表和静态图（或叠加层触发器的横条、播放列表和卡片）也会被删除。正在显示告警或仍在结束告警的触发器会被拒绝，返回 resource_conflict；请先结束它。追加 trigger.deleted。If-Match 用于保护修订。

替换触发器的密码并返回新密码，只返回一次。旧密码立即失效；请更新发送系统。正文中 signing 为 true 时，改为替换叠加层触发器的签名密钥并返回该密钥，只返回一次（触发器不签名时返回 400 invalid_request）。追加 trigger.updated，带有 details.rotated。

If-Match 用于保护修订。

在触发器的屏幕上显示一分钟的锻炼警报（带有黄色 EXERCISE 横幅的蓝色卡片），完全如接收到的警报一样，因此可以在不使用发送系统的情况下检查目标和屏幕。触发器显示警报时拒绝 resource_conflict，因此测试永远不会替换真实警报。

使用相同 Idempotency-Key 的完全相同的重试会返回 outcome duplicate。叠加层触发器会显示告警 screenrig-test（label Test，title Test overlay）一分钟，并返回 TriggerOverlayReceipt。

结束触发器警报（ended_reason cleared）并清除其设置的接管。被其他接管替代的屏幕保持不变。无活动警报的触发器返回不变。追加 trigger.alert_received，结果为 ended。

对于叠加层触发器，正文可以指定一个告警（alert_id）；不指定则所有告警结束，最后一个告警结束时横条收起，或接管结束。

紧急通知系统发布单个 CAP 1.2 警报的 URL（任何 XML 内容类型，最大 256 KiB）。使用触发器自身的 HTTP Basic 凭据认证：用户名为触发器 ID，密码为创建或轮换时返回的密码。

状态为 Actual 或 Exercise 且带有 msgType Alert 的消息，会在每个目标屏幕的默认播放列表上显示全屏卡片（标题、事件、描述、指令和发送者，极端、严重或无严重级别为红色，中等为橙色，轻微为蓝色；Exercise 增加黄色 EXERCISE 横幅），直至 <expires>，否则为 default_for_seconds，最长 7 天。

引用已显示警报的更新会在原位重绘它，并在 <expires> 变更时移动接管。引用它的取消或任何带有 responseType AllClear 的消息会结束它并清除其设置的接管。触发器只显示一个警报：新的警报替换已显示的警报。

测试、系统和草稿消息，确认和错误，已过期的提醒，以及未显示提醒的取消都会被忽略；相同发送者和标识符两次视为重复。回复是命名结果的回执；屏幕紧随其后写入（alert.screens.pending）。

接管绕过屏幕控制速率限制，且从不计费或因余额不足被拒绝。附加触发 trigger.alert_received。

外部系统（Home Assistant、摄像头、门传感器、告警工具，或给自己的 webhook 签名的服务商）推送所用的 URL，触发器的屏幕据此显示几句话。它使用触发器自己的密钥进行认证，放在 Authorization 请求头中（Bearer <secret>），或使用 HTTP Basic，用户名为触发器 ID。

当触发器创建时带有 verify，该服务商自己请求头中的有效签名（见 WebhookVerifyWrite）会代替密钥来验证这个请求，密钥仍可并行使用。

触发器签名时，还需要 ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret>，并且 t 必须在服务器时钟的五分钟以内。

未知的触发器、CAP 触发器、错误或缺失的密钥或签名、过期的时间戳、已停用的触发器以及每个 GET，都得到同样的 404 not_found；项目在触发器的投递日志中查看原因。

为服务商握手设置的触发器会最先响应它，在要求任何凭据之前，响应的是属于该握手的请求：Slack 的 url_verification 质询（已签名）、Microsoft Graph 的 validationToken、Asana 的 X-Hook-Secret（作为其事件的签名密钥加密封存保存）、monday.com 的 challenge、Azure Event Grid 的 SubscriptionValidationEvent，以及 Trello 的 HEAD 检查（此 URL 的 head 操作）。

握手不会改变任何告警，从不计费，也不消耗速率额度，并以结果 handshake 记录在投递日志中。

请求体最大 256 KiB，为 JSON、application/x-www-form-urlencoded 或 multipart/form-data（每个文本字段是 body.<field>，文件部分被忽略并计入投递日志）；有 mapping 时，由模板根据 body 和 query 构建请求。alert_id 指定告警：带有活动中 ID 的请求会更新该告警，而不是再叠加一条，并显示最近开始的告警。

每次触发或更新都会从该次推送起保持其告警 duration（10 到 604800 秒，或 10s, 5m, 2h, 1d, until_cleared；默认为触发器的默认值），因此持续推送的传感器会让叠加层一直保持。

clear 为 true 的推送，或表示结束的 state（off, closed, clear, cleared, resolved, ok, normal, inactive, ended），会结束具有该 ID 的告警；没有 ID 时结束所有告警。触发或更新算作一次计费的 API 请求；解除免费，且绝不会因余额而被拒绝。

Idempotency-Key（8 到 200 个字符）会在二十四小时内用第一份回执答复发送方的重试。每个触发器每分钟最多 120 次推送。

Trello 对新 webhook 所做的检查。对握手为 trello 的触发器，它以 200 响应且没有请求体；对其他所有触发器、地址和请求，则只有同一个 404 not_found，因此链接预览器什么也了解不到。它不写入任何内容，从不计费，也不消耗速率额度；已响应的检查会以结果 handshake 出现在投递日志中。

每个 GET 都响应 404，且不读取任何内容。

过去七天发往叠加层触发器的请求，最新的在前（最多 100 条），包含每个请求何时到达、如何结束（shown、updated、unchanged、ended、ignored、refused、invalid 或 handshake）、被拒绝或无效的原因（credentials、signature、signature_missing、signature_invalid、timestamp_missing、timestamp_stale、secret_pending、handshake_invalid、disabled、body、mapping、field、rate_limited、payment_required、internal）、状态、大小、multipart 请求所带文件部分的数量（被忽略）以及请求 ID。

它不保存正文、标头或凭据。CAP 触发器没有投递记录。