screentinker/Examples/PIP-Incident-Webhook/README.md

PiP Incident Webhook

An event-driven PiP example: a tiny webhook receiver that turns your monitoring stack's alerts into a floating ScreenTinker overlay — perfect for an engineering wall TV or NOC screen.

• alert firing → red overlay appears (kept until cleared)
• alert resolved → overlay disappears

Unlike the CAP / NOAA examples (which poll a feed), nothing happens here until your alerting system pushes to POST /webhook. Zero runtime dependencies — just Node 18+ (http + global fetch).

Payload shapes

It accepts either:

Generic (great for curl, cron jobs, custom scripts):

{ "status": "firing", "key": "db-down", "title": "Primary DB unreachable", "detail": "conn refused on 5432", "severity": "critical" }

Prometheus Alertmanager (point a webhook_config straight at it):

{ "status": "firing", "alerts": [
  { "status": "firing", "fingerprint": "abc123",
    "labels": { "alertname": "HighCPU", "severity": "warning", "instance": "web-1" },
    "annotations": { "summary": "CPU > 90%", "description": "web-1 hot for 5m" } }
]}

severity drives the band colour: critical→dark red, warning→orange, info→amber, anything else→red. The key (or Alertmanager fingerprint) is what matches a later resolve back to the overlay it should clear.

Setup

1. cp config.example.json config.json and fill in:
   • api_token — an st_ API token with the full scope.
   • api_base / overlay_base_url — your signage server.
   • device_id — a device or group id.
   • shared_secret (optional) — if set, callers must send it as the X-Webhook-Secret header or ?secret= query param.
2. Serve the overlay assets. The overlay is a web PiP rendered in an iframe, so the player fetches overlay_base_url directly. Copy incident-overlay.html and incident-overlay.js into the directory your signage server serves at the web root (e.g. the server's frontend/ dir) so that https://<server>/incident-overlay.html resolves. They must be same-origin with the player (the server CSP only allows same-origin scripts — that's why the JS is an external incident-overlay.js, not inline).
3. node server.js (or npm start).

Local quick-start (this repo's dev server)

cp config.example.json config.json
# edit config.json:
#   "api_base":          "https://localhost:3443/"
#   "api_token":         "st_REPLACE_WITH_A_FULL_SCOPE_TOKEN"
#   "overlay_base_url":  "https://localhost:3443/incident-overlay.html"
#   "device_id":         "DEVICE_OR_GROUP_ID"

# copy the overlay assets into the server's web root (served same-origin as the player):
cp incident-overlay.html incident-overlay.js ../../frontend/

# self-signed cert on localhost -> let Node accept it:
NODE_TLS_REJECT_UNAUTHORIZED=0 node server.js

Then drive it with curl:

# fire a critical incident -> red overlay appears on the player
curl -s localhost:8088/webhook -H 'Content-Type: application/json' -d \
  '{"status":"firing","key":"db-down","title":"Primary DB unreachable","detail":"conn refused on 5432","severity":"critical"}'

# ...later, resolve it -> overlay clears
curl -s localhost:8088/webhook -H 'Content-Type: application/json' -d \
  '{"status":"resolved","key":"db-down"}'

# health
curl -s localhost:8088/healthz

Ctrl-C clears any still-showing overlays before exiting.

Heads-up: this dev box has a shared player. If someone else is demoing on d7c88aa0-…, point device_id at your own device/group instead.

Wire up Alertmanager

# alertmanager.yml
route:
  receiver: signage
receivers:
  - name: signage
    webhook_configs:
      - url: http://YOUR_HOST:8088/webhook
        send_resolved: true        # so "resolved" clears the overlay

If you set a shared_secret, append it to the URL: ...:8088/webhook?secret=YOUR_SECRET.

Test

npm test   # offline; exercises both payload shapes + the colour map