Triggers CLI commands

CAP alert triggers

A trigger lets an emergency notification system, such as Everbridge, Rave, Alertus or an IPAWS relay, take screens over with CAP 1.2 alerts. Each trigger has its own URL, username and password, which you enter in the sending system as its CAP HTTP POST destination with HTTP Basic authentication. An organization has at most 20 triggers across its projects.

Triggers come in two kinds. A CAP trigger, described here, takes an emergency system's alerts. An overlay trigger shows what any sender posts, such as Home Assistant, a sensor hub or an alerting tool, as a bar over what plays or as a takeover; triggers create --kind overlay makes one, and triggers update, triggers clear and triggers rotate-secret serve both kinds, while triggers deliveries reads an overlay trigger's log.

A trigger targets a tag, resolved when each alert arrives, or up to 500 screen ids. Each Alert becomes a takeover of the trigger's own playlist: a full-screen card in the colour of its severity, with the event, headline, description and instruction. An Exercise adds an EXERCISE banner. The takeover holds until the alert's <expires>, else the trigger's --for default (1 minute to 7 days, 1 hour unless set), and never past 7 days. An Update redraws the card, and a Cancel or AllClear gives every screen back to what it played before. A new Alert replaces the one showing. Test, System and Draft messages, Ack and Error messages and expired alerts are ignored, and a repeated sender and identifier is a duplicate. A screen needs a default playlist to be taken over; other screens are skipped.

The password, srtg_…, is shown only by triggers create and triggers rotate-secret, with the warning trigger_password_shown_once. The CLI keeps it out of its configuration, operation log and recovery state. The URL and username are not secret.

triggers create --name NAME [--kind cap|overlay] (--tag TAG | --screen-id ID...) [--for DURATION] [--pull FILE]
    [--show bar|takeover] [--edge bottom|top] [--style FILE] [--map FILE] [--signing]
    [--verify VENDOR [--verify-secret-file FILE] [--verify-header NAME] [--verify-encoding hex|base64]
        [--verify-timestamp-header NAME] [--verify-tolerance SECONDS]]
    [--handshake VENDOR]

screenrig triggers create --name "Campus alerts" --tag Campus
screenrig triggers create --name "Campus alerts" --tag Campus --pull pull.json
screenrig triggers create --name "Lobby sensors" --kind overlay --show bar --tag Lobby
screenrig triggers create --name "Doorbell" --kind overlay --show takeover --tag Lobby --for 30s
screenrig triggers create --name "Payments" --kind overlay --show bar --tag Lobby --verify stripe --verify-secret-file stripe.secret --map stripe-map.json
screenrig triggers create --name "Boards" --kind overlay --show bar --tag Lobby --handshake trello

triggers list

screenrig triggers list

triggers show <id>

screenrig triggers show trg_01EXAMPLETRIGGER00

triggers test <id>

screenrig triggers test trg_01EXAMPLETRIGGER00

triggers update <id> [--name NAME] [--tag TAG | --screen-id ID...] [--for DURATION] [--pull FILE | --no-pull]
    [--edge bottom|top] [--style FILE | --clear-style] [--map FILE | --clear-map] [--enable | --disable]
    [--signing | --no-signing]
    [--verify VENDOR [--verify-secret-file FILE] [--verify-header NAME] [--verify-encoding hex|base64]
        [--verify-timestamp-header NAME] [--verify-tolerance SECONDS] | --clear-verify]
    [--handshake VENDOR | --clear-handshake] [--expect-rev REVISION]

screenrig triggers update trg_01EXAMPLETRIGGER00 --tag Lobby
screenrig triggers update trg_01EXAMPLETRIGGER00 --edge top --style style.json
screenrig triggers update trg_01EXAMPLETRIGGER00 --map map.json --signing
screenrig triggers update trg_01EXAMPLETRIGGER00 --verify github --verify-secret-file github.secret
screenrig triggers update trg_01EXAMPLETRIGGER00 --clear-verify

triggers deliveries <id> [--limit N]

screenrig triggers deliveries trg_01EXAMPLETRIGGER00 --limit 20

triggers clear <id> [--alert-id ID]

screenrig triggers clear trg_01EXAMPLETRIGGER00
screenrig triggers clear trg_01EXAMPLETRIGGER00 --alert-id front-door

triggers rotate-secret <id> [--signing] [--expect-rev REVISION]

screenrig triggers rotate-secret trg_01EXAMPLETRIGGER00

triggers delete <id> [--expect-rev REVISION]

screenrig triggers delete trg_01EXAMPLETRIGGER00

Overlay triggers

An overlay trigger shows what an outside system posts. Home Assistant, a door or motion sensor hub, a camera system or an alerting tool sends a few words with one HTTP POST, and the trigger's screens show them until they expire or the sender clears them. It is a trigger like a CAP trigger: triggers create --kind overlay makes it, and it counts toward the same limit of 20 per organization.

--show bar draws a strip over whatever plays on every target screen, on the bottom edge or, with --edge top, the top. The strip slides in when an alert starts and out when the last one ends; the playlist, its pages and its timing are untouched. A screen holds one bar per edge, so an overlay trigger whose edge a screen's other overlay trigger already holds does not show there (triggers show counts those screens as edge_taken), and a page that has its own strip with presence on that edge keeps it. A corner or chip card on that edge moves in past the bar's height whether or not the bar is showing. No bar draws on an ad slot page or while a takeover plays. --show takeover plays the alert full screen on target screens that have a default playlist from the first alert until the last one ends. A takeover trigger never replaces a takeover that is already on a screen, such as an operator's or an emergency alert, and a CAP alert replaces it.

A tag target is resolved when an alert starts; a screen tagged later gets the bar with the next alert that starts. Screens without a default playlist are skipped by a takeover. A screen that is offline catches up when it reconnects.

The sender posts JSON, a form or multipart/form-data (file parts are ignored) to data.url with Authorization: Bearer SECRET, or HTTP Basic with the trigger id as the username and the secret as the password. The secret never goes in the URL. A post has these members; an unknown member is refused naming it.

A raise needs at least one of label, title, message and note. Text longer than its limit is refused, and duration outside 10 seconds to 7 days is refused, both with invalid_request naming the member. Every raise or update holds its alert for duration from that post, so a motion sensor that posts every few seconds keeps the bar up and the bar leaves duration after the last post. A trigger shows its newest alert; ending it shows the one before it again. It holds ten alerts, and an eleventh replaces the oldest. An alert ends within about ten seconds of its time. A clear sent twice ends the alert once, and a clear of an alert that is not active changes nothing.

The answer is a receipt: outcome (shown, updated, unchanged, ended or ignored), alert_id, until (null for an alert held until cleared) and active, the alerts the trigger holds after the post. An Idempotency-Key header of 8 to 200 characters answers a sender's retry with the first receipt for 24 hours. A trigger takes 120 posts a minute. A post does not count toward the agent request cap, and a clear is never refused, so an alert can always be taken off the screens.

curl -X POST https://api.screenrig.ai/api/triggers/trg_01EXAMPLETRIGGER00/overlay \
  -H "Authorization: Bearer srtg_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"alert_id":"front-door","title":"Front door","message":"The front door is open","duration":"10m"}'

A wrong address, a wrong secret, a disabled trigger, a missing or bad signature and every GET answer the same 404 not_found, so a sender or a link previewer learns nothing about which it was. triggers deliveries shows the project why, for the last seven days, with no post body. --style FILE sets the text card's theme, accent, background, backgroundColor, textColor and align; use one trigger per look.

--map FILE builds the post from the body an alerting tool sends, with the template language of card webhooks. A string with {{body.title}} is text, a string that is exactly one placeholder keeps its type, {"$text": "{{body.message}}", "$max": 400} cuts text, and a path starts with body or query. This template maps an alert from a monitoring tool and clears it when its status is resolved:

{"alert_id": "{{body.groupKey}}", "title": "{{body.title}}", "message": {"$text": "{{body.message}}", "$max": 400}, "state": "{{body.status}}"}

--signing also requires ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed with data.signing_secret (whsec_…, shown once), with t within five minutes of the server's clock. A sender may carry two v1 values while it rotates the secret.

body='{"alert_id":"front-door","title":"Front door","message":"The front door is open"}'
t=$(date +%s)
sig=$(printf '%s.%s' "$t" "$body" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex | sed 's/^.* //')
curl -X POST "$URL" -H "Authorization: Bearer $SECRET" -H "ScreenRig-Signature: t=$t,v1=$sig" \
  -H "Content-Type: application/json" -d "$body"

An alerting tool or a vendor that signs its own posts can have its signature verified in place of the secret, and a vendor's setup handshake answered, as for card webhooks: triggers create and triggers update take --verify VENDOR with --verify-secret-file FILE, and --handshake VENDOR, and triggers update takes --clear-verify and --clear-handshake to remove each. The vendors, their headers and the generic_hmac options are the ones listed there. A post that carries the vendor's valid signature is accepted without the trigger's srtg_ password, which keeps working beside it, --verify excludes --signing, and a handshake changes no alert. triggers deliveries shows why a signature failed.

A Home Assistant rest_command posts to the trigger. Keep the secret in secrets.yaml, and give each automation the alert it raises or clears:

# secrets.yaml
screenrig_lobby_overlay: "Bearer srtg_YOUR_SECRET"

# configuration.yaml
rest_command:
  screenrig_lobby:
    url: "https://api.screenrig.ai/api/triggers/trg_01EXAMPLETRIGGER00/overlay"
    method: post
    headers:
      Authorization: !secret screenrig_lobby_overlay
    content_type: "application/json"
    payload: >-
      {{ {"alert_id": alert_id | default(""), "title": title | default(""),
          "message": message | default(""), "duration": duration | default("10m"),
          "clear": clear | default(false)} | tojson }}

# automations.yaml
- alias: Front door open on the lobby screens
  triggers:
    - trigger: state
      entity_id: binary_sensor.front_door
      to: "on"
  actions:
    - action: rest_command.screenrig_lobby
      data: {alert_id: front-door, title: Front door, message: The front door is open, duration: until_cleared}
- alias: Front door closed
  triggers:
    - trigger: state
      entity_id: binary_sensor.front_door
      to: "off"
  actions:
    - action: rest_command.screenrig_lobby
      data: {alert_id: front-door, clear: true}
- alias: Driveway motion
  triggers:
    - trigger: state
      entity_id: binary_sensor.driveway_motion
      to: "on"
  actions:
    - action: rest_command.screenrig_lobby
      data: {alert_id: driveway, title: Driveway, message: Motion at the driveway, duration: 2m}

Two facts make this work. Each motion post holds the bar for 2 minutes from that post, so it stays while motion continues and leaves 2 minutes after the last event. And Home Assistant renders the {{ }} template before it posts, so the trigger receives plain JSON; the trigger's own --map template is a separate step that runs every post through it, so leave --map off for a sender that already posts the overlay members, as Home Assistant does here, or give that sender its own trigger.