Alarm-Auslöser-API

Listet die Trigger des Projekts (CAP und Overlay), älteste zuerst (höchstens 20), jeweils mit ihrer Eingangs-url, ihrem username und ihrer letzten Meldung oder ihrem Overlay-Zustand. Hier wird nie ein Geheimnis zurückgegeben.

Erstellt einen CAP-Alarm-Trigger: eine eingehende URL, an die ein Notifikationssystem (Everbridge, Rave, Alertus, IPAWS-Relays und andere CAP 1.2 Sender) Alarme mit HTTP Basic-Zugangsdaten sendet.

Die Antwort ist der einzige Ort, an dem das Passwort erscheint (mit der Antwort drehen): Speichern Sie es sofort im sendenden System. Ziel ist ein Tag (jeder aktive Bildschirm mit diesem, wenn die Warnung eintrifft) oder bis zu 500 screen_ids.

Eine Warnung übernimmt jeden Zielbildschirm mit einer Standard-Playlist bis zum <expires> der Warnung, sonst für default_for_seconds (60 bis 604800, Standard 3600); siehe POST /api/triggers/{id}/cap. Eine Organisation hat höchstens 20 Trigger über alle ihre Projekte (trigger_limit_reached). Fügt trigger.created hinzu.

Ein exakter Wiederholungsversuch mit demselben Idempotency-Key gibt dieselbe Antwort, einschließlich Passwort, für vierundzwanzig Stunden zurück.

Das optionale pull fügt CAP-Quellen hinzu, die die Plattform für den Trigger liest (siehe CapPull); die Eingangs-url funktioniert daneben weiter. kind overlay legt stattdessen die zweite Art an: eine Eingangs-url (POST /api/triggers/{id}/overlay), an die ein beliebiges System (Home Assistant, eine Kamera, ein Alarmierungswerkzeug) wenige Worte sendet, die auf den Zielbildschirmen als Streifen über dem Laufenden (overlay.show bar, am unteren oder oberen Rand) oder als Übernahme (overlay.show takeover) angezeigt werden, solange eine Meldung läuft; siehe TriggerOverlay.

Mit signing true enthält die Antwort einmalig auch das Signaturgeheimnis. verify lässt die eigene Signatur eines Anbieters (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana oder ein beliebiger HMAC-Sender) eine Zustellung anstelle des Passworts authentifizieren, das daneben weiter funktioniert; es lässt sich nicht mit signing kombinieren, und sein Secret wird versiegelt und nie zurückgegeben, nur ein Hinweis darauf. handshake nennt einen Anbieter-Handshake, den die URL beantwortet (Microsoft Graph, monday.com, Trello oder Azure Event Grid; verify slack und asana beantworten ihren eigenen).

Overlay-Haltezeiten betragen 10 bis 604800 Sekunden (Standard 600). Ein Trigger, dessen Selektor einen geschützten Bildschirm erreicht, ist protected_target (409), und ein fehlgeschlagenes Lesen des Bildschirmschutzes ist dependency_unavailable (500, dieselbe Anfrage wiederholen); ein Trigger steht einem auf Bildschirme beschränkten Aufrufer nicht zur Verfügung.

Ein Trigger mit seiner letzten Meldung oder, bei einem Overlay-Trigger, seinen aktiven Meldungen (neueste zuerst, die erste wird angezeigt), den Verteilzahlen und der Angabe, ob noch Arbeit aussteht. Eine Meldung nach ihrem until wird als beendet mit ended_reason expired gelesen.

Ändert einen Trigger, ohne seine URL oder sein Geheimnis zu ändern: label, target, default_for_seconds, das pull eines CAP-Triggers (null entfernt es) und bei einem Overlay-Trigger overlay.edge, style (ersetzt den ganzen Stil; null löscht ihn), mapping (null entfernt es), enabled, signing, verify (null entfernt es; ohne Secret behält es das gespeicherte, wenn der Anbieter derselbe ist) und handshake (null entfernt es).

Ein deaktivierter Overlay-Trigger beantwortet seinen Absender mit demselben 404 wie ein falsches Geheimnis. Das Einschalten der Signatur gibt das Signaturgeheimnis einmal in dieser Antwort zurück. Ein Streifen ordnet sich auf den neuen Zielbildschirmen und am neuen Rand neu ein; das neue Ziel eines Übernahme-Triggers gilt ab der nächsten beginnenden Meldung. Hängt trigger.updated mit details.changed an. If-Match schützt die Revision.

Jedes Update wird gegen das Ziel geprüft, das der Trigger haben wird, das neue oder sonst das gespeicherte: Ein Ziel, das einen geschützten Bildschirm erreicht, ist protected_target (409), egal welches Mitglied ändert, und ein fehlgeschlagenes Lesen des Bildschirmschutzes ist dependency_unavailable (500, dieselbe Anfrage wiederholen).

Löscht den Trigger. Seine URL funktioniert sofort nicht mehr, und seine Alarm-Playlist und Standbilder (oder die Streifen, die Playlist und die Karte eines Overlay-Triggers) werden gelöscht. Ein Trigger, der eine Meldung zeigt oder noch eine beendet, wird mit resource_conflict abgelehnt; beenden Sie sie zuerst. Hängt trigger.deleted an. If-Match schützt die Revision.

Ersetzt das Passwort des Triggers und gibt das neue einmal zurück. Das alte Passwort funktioniert sofort nicht mehr; aktualisieren Sie das sendende System. Mit signing true im Body ersetzt es stattdessen das Signaturgeheimnis eines Overlay-Triggers und gibt dieses einmal zurück (400 invalid_request, wenn der Trigger nicht signiert). Hängt trigger.updated mit details.rotated an.

If-Match schützt die Revision.

Zeigt eine einminütige Exercise-Warnung (eine blaue Karte mit gelbem EXERCISE-Banner) auf den Bildschirmen des Auslösers, genau wie eine empfangene Warnung, sodass Zielsetzung und Bildschirme ohne das sendende System geprüft werden können. Verweigert resource_conflict, während der Auslöser eine Warnung zeigt, sodass ein Test niemals eine echte ersetzt.

Eine exakte Wiederholung mit demselben Idempotency-Key beantwortet outcome duplicate. Ein Overlay-Trigger zeigt die Meldung screenrig-test (label Test, title Test overlay) eine Minute lang und antwortet mit einem TriggerOverlayReceipt.

Beendet den Alarm des Triggers (ended_reason cleared) und löscht die von ihm gesetzten Übernahmen. Ein Bildschirm, der seitdem von einer anderen Übernahme ersetzt wurde, bleibt unberührt. Ein Trigger ohne aktiven Alarm antwortet unverändert. Fügt trigger.alert_received mit Ergebnis ended hinzu.

Bei einem Overlay-Trigger kann der Body eine Meldung nennen (alert_id); ohne sie enden alle Meldungen, und mit dem Ende der letzten wird der Streifen gesenkt oder werden die Übernahmen beendet.

Die URL, an die ein Notifikationssystem eine CAP 1.2-Warnung sendet (beliebiger XML-Inhaltstyp, maximal 256 KiB). Die Authentifizierung erfolgt mit den HTTP-Basic-Zugangsdaten des Triggers: Benutzername ist die Trigger-ID, Passwort das bei Erstellung oder Rotation zurückgegebene.

Eine Nachricht mit Status Actual oder Exercise und msgType Alert zeigt auf jedem Zielbildschirm mit einer Standard-Playlist eine Vollbildkarte (Überschrift, Ereignis, Beschreibung, Anweisung und Absender, rot für Extreme, Severe oder keine Schwere, bernsteinfarben für Moderate, blau für Minor; Exercise fügt ein gelbes EXERCISE-Banner hinzu), bis <expires> oder sonst für default_for_seconds, maximal 7 Tage.

Ein Update, das sich auf die angezeigte Warnung bezieht, zeichnet diese an Ort und Stelle neu und verschiebt die Übernahmen, wenn sich <expires> geändert hat. Ein Abbrechen, das sich darauf bezieht, oder jede Nachricht mit responseType AllClear beendet sie und löscht die von ihr gesetzten Übernahmen. Ein Trigger zeigt eine Warnung an: eine neue Warnung ersetzt die angezeigte.

Test-, System- und Entwurfsnachrichten, Bestätigung und Fehler, eine bereits abgelaufene Warnung sowie ein Abbruch einer nicht angezeigten Warnung werden ignoriert; derselbe Absender und dieselbe Kennung zweimal sind ein Duplikat. Die Antwort ist eine Quittung mit dem Ergebnis; die Bildschirme werden direkt danach beschrieben (alert.screens.pending).

Die Übernahmen umgehen die Bildschirmsteuerungs-Rate-Limits und werden nie gemessen oder wegen Guthabenmangel abgelehnt. Fügt trigger.alert_received hinzu.

Die URL, an die ein externes System (Home Assistant, eine Kamera, ein Türsensor, ein Alarmierungswerkzeug oder ein Anbieter, der seine eigenen Webhooks signiert) sendet, damit die Bildschirme des Triggers wenige Worte zeigen. Es authentifiziert sich mit dem eigenen Geheimnis des Triggers im Header Authorization: Bearer <secret> oder mit HTTP Basic, die Trigger-ID als Benutzername.

Wurde der Trigger mit verify angelegt, authentifiziert eine gültige Signatur im eigenen Header dieses Anbieters (siehe WebhookVerifyWrite) die Zustellung anstelle des Secrets, das daneben weiter funktioniert.

Wenn der Trigger signiert, ist zusätzlich ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret> erforderlich, und t muss innerhalb von fünf Minuten zur Uhr des Servers liegen.

Ein unbekannter Trigger, ein CAP-Trigger, ein falsches oder fehlendes Secret oder eine falsche oder fehlende Signatur, ein veralteter Zeitstempel, ein deaktivierter Trigger und jedes GET erhalten dasselbe 404 not_found; das Projekt sieht den Grund im Zustellprotokoll des Triggers.

Ein Trigger, der für einen Anbieter-Handshake eingerichtet ist, beantwortet ihn zuerst, bevor irgendwelche Zugangsdaten verlangt werden, auf eine Anfrage, die dieser Handshake ist: die url_verification-Challenge von Slack (signiert), das validationToken von Microsoft Graph, das X-Hook-Secret von Asana (versiegelt als Signing-Secret seiner Ereignisse aufbewahrt), die challenge von monday.com, das SubscriptionValidationEvent von Azure Event Grid und die HEAD-Prüfung von Trello (die head-Operation dieser URL).

Ein Handshake ändert keine Meldung, wird nie abgerechnet und verbraucht kein Ratenbudget und wird im Zustellprotokoll mit dem Ergebnis handshake festgehalten.

Der Body, höchstens 256 KiB, ist JSON, application/x-www-form-urlencoded oder multipart/form-data (jedes Textfeld ist body.<field>, Dateiteile werden ignoriert und im Zustellprotokoll gezählt); mit einem mapping baut die Vorlage die Anfrage aus body und query. alert_id benennt die Meldung: Eine Zustellung mit einer aktiven ID aktualisiert diese Meldung, statt eine weitere zu stapeln, und die zuletzt gestartete Meldung wird angezeigt.

Jedes Auslösen oder Aktualisieren hält seine Meldung duration ab dieser Sendung (10 bis 604800 Sekunden oder 10s, 5m, 2h, 1d oder until_cleared; Standard ist der des Triggers), sodass ein Sensor, der weitersendet, das Overlay oben hält.

Eine Sendung mit clear true oder einem state, der "vorbei" bedeutet (off, closed, clear, cleared, resolved, ok, normal, inactive, ended), beendet die Meldung mit dieser ID, ohne ID alle Meldungen. Ein Auslösen oder Aktualisieren ist eine abgerechnete API-Anfrage; ein Beenden ist kostenlos und wird nie wegen des Guthabens abgelehnt.

Idempotency-Key (8 bis 200 Zeichen) beantwortet die Wiederholung eines Absenders vierundzwanzig Stunden lang mit der ersten Quittung. Höchstens 120 Sendungen pro Minute pro Trigger.

Die Prüfung, die Trello bei einem neuen Webhook vornimmt. Sie antwortet mit 200 ohne Body für einen Trigger, dessen Handshake trello ist, und mit dem einen 404 not_found für jeden anderen Trigger, jede andere Adresse und Anfrage, sodass eine Link-Vorschau nichts erfährt. Sie schreibt nichts, wird nie abgerechnet und verbraucht kein Ratenbudget; die beantwortete Prüfung steht im Zustellprotokoll mit dem Ergebnis handshake.

Jedes GET antwortet mit dem 404 und liest nichts.

Die Zustellungen an einen Overlay-Trigger der letzten sieben Tage, neueste zuerst (höchstens 100), mit dem Zeitpunkt des Eingangs, dem Ausgang jeder einzelnen (shown, updated, unchanged, ended, ignored, refused, invalid oder handshake), dem Grund, warum eine abgelehnte oder ungültige es war (credentials, signature, signature_missing, signature_invalid, timestamp_missing, timestamp_stale, secret_pending, handshake_invalid, disabled, body, mapping, field, rate_limited, payment_required, internal), dem Status, der Größe, der Anzahl der Dateiteile, die eine Multipart-Zustellung trug (ignoriert), und der Anfrage-ID.

Es speichert weder Body noch Header noch Zugangsdaten. Ein CAP-Trigger hat keine.