Alert triggers API

Lists the project's triggers (CAP alert and overlay), oldest first (at most 20), each with its ingest url, username and latest alert or overlay state. No secret is ever returned here.

Creates a CAP alert trigger: one inbound URL an emergency notification system (Everbridge, Rave, Alertus, IPAWS relays and other CAP 1.2 senders) posts alerts to, with HTTP Basic credentials.

The answer is the only place the password appears (with the rotate answer): store it in the sending system at once. target is a tag (every active screen with it when the alert arrives) or up to 500 screen_ids.

An alert takes every target screen with a default playlist over until the alert's <expires>, else for default_for_seconds (60 to 604800, default 3600); see POST /api/triggers/{id}/cap. An organization has at most 20 triggers across its projects (trigger_limit_reached). Appends trigger.created.

An exact retry with the same Idempotency-Key returns this same answer, password included, for twenty-four hours.

Optional pull adds CAP sources the platform reads for the trigger (see CapPull); the ingest url keeps working beside it. kind overlay creates the second kind instead: one inbound URL (POST /api/triggers/{id}/overlay) any system (Home Assistant, a camera, an alerting tool) posts a few words to, shown on the target screens as a bar over whatever plays (overlay.show bar, on the bottom or top edge) or as a takeover (overlay.show takeover) while an alert lasts; see TriggerOverlay.

With signing true the answer also carries the signing secret once. verify makes a vendor's own signature (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana or any HMAC sender) authenticate a post in place of the password, which keeps working beside it; it cannot be combined with signing, and its secret is sealed and never returned, only a hint of it. handshake names a vendor handshake the URL answers (Microsoft Graph, monday.com, Trello or Azure Event Grid; verify slack and asana answer theirs).

Overlay holds are 10 to 604800 seconds (default 600). A trigger whose selector reaches a protected screen is protected_target (409), and a failed read of screen protection is dependency_unavailable (500, retry the same request); a trigger is not available to a caller limited to screens.

One trigger with its latest alert, or for an overlay trigger its active alerts (newest first, the first shows), the fan-out counts and whether work is pending. An alert past its until reads as ended with ended_reason expired.

Changes a trigger without changing its URL or secret: label, target, default_for_seconds, a CAP trigger's pull (null removes it), and for an overlay trigger overlay.edge, style (replaces the whole style; null clears it), mapping (null removes it), enabled, signing, verify (null removes it; without a secret it keeps the stored one when the vendor is the same) and handshake (null removes it).

A disabled overlay trigger answers its sender the same 404 as a wrong secret. Turning signing on returns the signing secret once in this answer. A bar re-places itself on the new target screens and edge; a takeover trigger's new target applies from the next alert that starts. Appends trigger.updated with details.changed. If-Match guards the revision.

Every update is checked on the target the trigger will have, the new one or else the stored one: a target that reaches a protected screen is protected_target (409) whichever member changes, and a failed read of screen protection is dependency_unavailable (500, retry the same request).

Deletes the trigger. Its URL stops working at once, and its alert playlist and stills (or an overlay trigger's bars, playlist and card) are deleted. A trigger showing an alert, or still clearing one, is refused resource_conflict; clear it first. Appends trigger.deleted. If-Match guards the revision.

Replaces the trigger's password and returns the new one, once. The old password stops working at once; update the sending system. With signing true in the body it replaces an overlay trigger's signing secret instead and returns that one, once (400 invalid_request when the trigger does not sign). Appends trigger.updated with details.rotated.

If-Match guards the revision.

Shows a one-minute Exercise alert (a blue card with a yellow EXERCISE banner) on the trigger's screens, exactly as a received alert would, so the targeting and the screens can be checked without the sending system. Refused resource_conflict while the trigger shows an alert, so a test never replaces a real one.

An exact retry with the same Idempotency-Key answers outcome duplicate. An overlay trigger shows the alert screenrig-test (label Test, title Test overlay) for a minute and answers a TriggerOverlayReceipt.

Ends the trigger's alert (ended_reason cleared) and clears the takeovers it set. A screen another takeover has replaced since is left alone. A trigger without an active alert answers unchanged. Appends trigger.alert_received with outcome ended.

For an overlay trigger the body may name one alert (alert_id); without one every alert ends, and the last one ending lowers the bar or clears the takeovers.

The URL an emergency notification system posts one CAP 1.2 alert to (any XML content type, at most 256 KiB). It authenticates with the trigger's own HTTP Basic credentials: the username is the trigger id, the password the one create or rotate returned.

A message with status Actual or Exercise and msgType Alert shows a full-screen card (headline, event, description, instruction and sender, red for Extreme, Severe or no severity, amber for Moderate, blue for Minor; Exercise adds a yellow EXERCISE banner) on every target screen with a default playlist, until <expires>, else for default_for_seconds, at most 7 days.

An Update that references the shown alert redraws it in place and moves the takeovers when <expires> changed. A Cancel that references it, or any message with responseType AllClear, ends it and clears the takeovers it set. A trigger shows one alert: a new Alert replaces the shown one.

Test, System and Draft messages, Ack and Error, an alert already expired, and a Cancel of an alert not shown are ignored; the same sender and identifier twice is a duplicate. The answer is a receipt naming the outcome; the screens are written right after it (alert.screens.pending).

The takeovers bypass the screen-control rate limits and are never metered or refused for balance. Appends trigger.alert_received.

The URL an outside system (Home Assistant, a camera, a door sensor, an alerting tool, or a vendor that signs its own webhooks) posts to so the trigger's screens show a few words. It authenticates with the trigger's own secret in the Authorization header: Bearer <secret>, or HTTP Basic with the trigger id as the username.

When the trigger was created with verify, a valid signature in that vendor's own header (see WebhookVerifyWrite) authenticates the post in place of the secret, which keeps working beside it.

When the trigger signs, ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret> is also required, and t must be within five minutes of the server's clock.

An unknown trigger, a CAP trigger, a wrong or missing secret or signature, a stale timestamp, a disabled trigger and every GET answer the same 404 not_found; the project sees the reason in the trigger's delivery log.

A trigger set up for a vendor handshake answers it first, before any credential is asked for, to a request that is that handshake: Slack's url_verification challenge (signed), Microsoft Graph's validationToken, Asana's X-Hook-Secret (kept sealed as the signing secret of its events), monday.com's challenge, Azure Event Grid's SubscriptionValidationEvent, and Trello's HEAD check (the head operation of this URL).

A handshake changes no alert, is never billed and spends no rate budget, and is recorded in the delivery log with outcome handshake.

The body, at most 256 KiB, is JSON, application/x-www-form-urlencoded or multipart/form-data (each text field is body.<field>, file parts are ignored and counted in the delivery log); with a mapping the template builds the request from body and query. alert_id names the alert: a post with an id that is active updates that alert instead of stacking another, and the newest started alert shows.

Every raise or update holds its alert for duration from that post (10 to 604800 seconds, or 10s, 5m, 2h, 1d, or until_cleared; default the trigger's), so a sensor that keeps posting keeps the overlay up.

A post with clear true, or a state that means over (off, closed, clear, cleared, resolved, ok, normal, inactive, ended), ends the alert with that id, or every alert without one. A raise or update is one billed API request; a clear is free and never refused for balance.

Idempotency-Key (8 to 200 characters) answers a sender's retry with the first receipt for twenty-four hours. At most 120 posts per minute per trigger.

The check Trello makes of a new webhook. It answers 200 with no body for a trigger whose handshake is trello, and the one 404 not_found for every other trigger, address and request, so a link previewer learns nothing. It writes nothing, is never billed and spends no rate budget; the answered check is in the delivery log with outcome handshake.

Every GET answers the 404 and reads nothing.

The posts to an overlay trigger over the last seven days, newest first (at most 100), with when each arrived, how each ended (shown, updated, unchanged, ended, ignored, refused, invalid or handshake), why a refused or invalid one was (credentials, signature, signature_missing, signature_invalid, timestamp_missing, timestamp_stale, secret_pending, handshake_invalid, disabled, body, mapping, field, rate_limited, payment_required, internal), the status, the size, the number of file parts a multipart post carried (ignored) and the request id.

It keeps no body, header or credential. A CAP trigger lists none.