API Trigger di allerta

Elenca i trigger del progetto (CAP e di sovrapposizione), dal più vecchio (al massimo 20), ciascuno con il suo url di ingresso, il suo username e l'ultimo avviso o stato di sovrapposizione. Qui non viene mai restituito alcun segreto.

Crea un trigger di allerta CAP: un URL in ingresso a cui un sistema di notifiche di emergenza (Everbridge, Rave, Alertus, relè IPAWS e altri mittenti CAP 1.2) invia avvisi, con credenziali HTTP Basic.

La risposta è l’unico luogo in cui appare la password (con la risposta di rotazione): conservarla subito nel sistema di invio. target è un tag (ogni schermo attivo con esso all’arrivo dell’avviso) o fino a 500 screen_ids.

Un avviso prende ogni schermo target con playlist predefinita fino a <expires> dell’avviso, altrimenti per default_for_seconds (60 a 604800, default 3600); vedi POST /api/triggers/{id}/cap. Un’organizzazione ha al massimo 20 trigger in tutti i suoi progetti (trigger_limit_reached). Aggiunge trigger.created.

Un retry esatto con la stessa Idempotency-Key restituisce questa stessa risposta, password inclusa, per ventiquattro ore.

Il pull facoltativo aggiunge fonti CAP che la piattaforma legge per il trigger (vedi CapPull); l'url di ingresso continua a funzionare accanto. kind overlay crea invece il secondo tipo: un url di ingresso (POST /api/triggers/{id}/overlay) a cui qualsiasi sistema (Home Assistant, una telecamera, uno strumento di allerta) invia poche parole, mostrate sugli schermi di destinazione come fascia sopra ciò che viene riprodotto (overlay.show bar, sul bordo inferiore o superiore) o come acquisizione (overlay.show takeover) finché un avviso dura; vedi TriggerOverlay.

Con signing true la risposta porta anche il segreto di firma, una sola volta. verify fa autenticare un invio dalla firma propria di un fornitore (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana o qualsiasi mittente HMAC) al posto della password, che continua a funzionare accanto; non può essere combinato con signing, e il suo segreto è sigillato e non viene mai restituito, solo un suggerimento. handshake indica un handshake di fornitore a cui risponde l’URL (Microsoft Graph, monday.com, Trello o Azure Event Grid; verify slack e asana rispondono al proprio).

Le durate di permanenza della sovrapposizione vanno da 10 a 604800 secondi (predefinito 600). Un trigger il cui selettore raggiunge uno schermo protetto è protected_target (409), e una lettura non riuscita della protezione degli schermi è dependency_unavailable (500, ripeti la stessa richiesta); un trigger non è disponibile per un chiamante limitato agli schermi.

Un trigger con il suo ultimo avviso o, per un trigger di sovrapposizione, i suoi avvisi attivi (il più recente per primo, il primo viene mostrato), i conteggi della distribuzione e se c'è lavoro in sospeso. Un avviso oltre il suo until viene letto come terminato con ended_reason expired.

Modifica un trigger senza cambiare il suo URL né il suo segreto: label, target, default_for_seconds, il pull di un trigger CAP (null lo rimuove) e, per un trigger di sovrapposizione, overlay.edge, style (sostituisce l’intero stile; null lo cancella), mapping (null lo rimuove), enabled, signing, verify (null lo rimuove; senza un segreto conserva quello memorizzato quando il fornitore è lo stesso) e handshake (null lo rimuove).

Un trigger di sovrapposizione disattivato risponde al suo mittente con lo stesso 404 di un segreto errato. Attivare la firma restituisce il segreto di firma una sola volta in questa risposta. Una fascia si riposiziona sui nuovi schermi di destinazione e sul nuovo bordo; la nuova destinazione di un trigger di acquisizione vale dal prossimo avviso che inizia. Aggiunge trigger.updated con details.changed. If-Match protegge la revisione.

Ogni aggiornamento viene controllato sulla destinazione che il trigger avrà, quella nuova o altrimenti quella memorizzata: una destinazione che raggiunge uno schermo protetto è protected_target (409) qualunque membro la modifichi, e una lettura non riuscita della protezione degli schermi è dependency_unavailable (500, ripeti la stessa richiesta).

Elimina il trigger. Il suo URL smette subito di funzionare, e la sua playlist di avvisi e i fermi immagine (o le fasce, la playlist e la scheda di un trigger di sovrapposizione) vengono eliminati. Un trigger che mostra un avviso, o ne sta ancora terminando uno, viene rifiutato con resource_conflict; terminalo prima. Aggiunge trigger.deleted. If-Match protegge la revisione.

Sostituisce la password del trigger e restituisce quella nuova, una sola volta. La vecchia password smette subito di funzionare; aggiorna il sistema mittente. Con signing true nel corpo sostituisce invece il segreto di firma di un trigger di sovrapposizione e restituisce quello, una sola volta (400 invalid_request quando il trigger non firma). Aggiunge trigger.updated con details.rotated.

If-Match protegge la revisione.

Mostra un avviso di esercizio di un minuto (una scheda blu con una banda gialla EXERCISE) sugli schermi del trigger, esattamente come farebbe un avviso ricevuto, così da poter verificare il targeting e gli schermi senza il sistema di invio. Rifiutato resource_conflict mentre il trigger mostra un avviso, così un test non sostituisce mai uno reale.

Un nuovo tentativo identico con la stessa Idempotency-Key risponde con outcome duplicate. Un trigger di sovrapposizione mostra l'avviso screenrig-test (label Test, title Test overlay) per un minuto e risponde con un TriggerOverlayReceipt.

Termina l’allerta del trigger (ended_reason cleared) e cancella i takeover impostati. Uno schermo sostituito da un altro takeover resta invariato. Un trigger senza allerta attiva risponde invariato. Aggiunge trigger.alert_received con esito ended.

Per un trigger di sovrapposizione il corpo può nominare un avviso (alert_id); senza, terminano tutti gli avvisi, e la fine dell'ultimo abbassa la fascia o termina le acquisizioni.

L’URL a cui un sistema di notifiche di emergenza invia un avviso CAP 1.2 (qualsiasi tipo di contenuto XML, massimo 256 KiB). Si autentica con le credenziali HTTP Basic del trigger: username è l’id trigger, password quella restituita da create o rotate.

Un messaggio con stato Actual o Exercise e tipo msgType Alert mostra una scheda a schermo intero (titolo, evento, descrizione, istruzioni e mittente, rosso per Extreme, Severe o nessuna gravità, ambra per Moderate, blu per Minor; Exercise aggiunge un banner giallo EXERCISE) su ogni schermo target con playlist predefinita, fino a <expires>, altrimenti per default_for_seconds, massimo 7 giorni.

Un aggiornamento che fa riferimento all’avviso mostrato lo ridisegna in loco e sposta i takeover quando <expires> cambia. Un annulla che lo fa riferimento, o qualsiasi messaggio con responseType AllClear, lo termina e cancella i takeover impostati. Un trigger mostra un solo avviso: un nuovo avviso sostituisce quello mostrato.

Messaggi Test, System e Draft, Ack ed Error, un avviso già scaduto e una cancellazione di un avviso non mostrato sono ignorati; lo stesso mittente e identificatore due volte è un duplicato. La risposta è una ricevuta che indica l’esito; gli schermi sono scritti subito dopo (alert.screens.pending).

I takeover bypassano i limiti di frequenza del controllo schermo e non sono mai conteggiati o rifiutati per saldo. Aggiunge trigger.alert_received.

L’URL a cui un sistema esterno (Home Assistant, una telecamera, un sensore di porta, uno strumento di allerta o un fornitore che firma i propri webhook) invia perché gli schermi del trigger mostrino poche parole. Si autentica con il segreto proprio del trigger nell’intestazione Authorization: Bearer <secret>, oppure con HTTP Basic usando l’id del trigger come nome utente.

Quando il trigger è stato creato con verify, una firma valida nell’intestazione propria di quel fornitore (vedi WebhookVerifyWrite) autentica l’invio al posto del segreto, che continua a funzionare accanto.

Quando il trigger firma, è richiesto anche ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret>, e t deve distare al massimo cinque minuti dall'orologio del server.

Un trigger sconosciuto, un trigger CAP, un segreto o una firma sbagliati o mancanti, un timestamp scaduto, un trigger disattivato e ogni GET ricevono lo stesso 404 not_found; il progetto vede il motivo nel registro delle consegne del trigger.

Un trigger configurato per un handshake di fornitore risponde per primo, prima che venga richiesta qualsiasi credenziale, a una richiesta che è quell’handshake: la sfida url_verification di Slack (firmata), il validationToken di Microsoft Graph, l’X-Hook-Secret di Asana (conservato sigillato come segreto di firma dei suoi eventi), la challenge di monday.com, il SubscriptionValidationEvent di Azure Event Grid e il controllo HEAD di Trello (l’operazione head di questo URL).

Un handshake non cambia alcun avviso, non viene mai fatturato e non consuma budget di frequenza, ed è registrato nel registro delle consegne con l’esito handshake.

Il corpo, al massimo 256 KiB, è JSON, application/x-www-form-urlencoded o multipart/form-data (ogni campo di testo è body.<field>, le parti di file vengono ignorate e contate nel registro delle consegne); con un mapping il modello costruisce la richiesta da body e query. alert_id indica l’avviso: un invio con un id attivo aggiorna quell’avviso invece di impilarne un altro, e viene mostrato l’avviso avviato più di recente.

Ogni attivazione o aggiornamento trattiene il suo avviso per duration da quell'invio (da 10 a 604800 secondi, oppure 10s, 5m, 2h, 1d, o until_cleared; per impostazione predefinita quello del trigger), così un sensore che continua a inviare mantiene la sovrapposizione.

Un invio con clear true, o uno state che significa che è finita (off, closed, clear, cleared, resolved, ok, normal, inactive, ended), termina l'avviso con quell'id, o tutti gli avvisi se manca. Un'attivazione o un aggiornamento è una richiesta API fatturata; una chiusura è gratuita e non viene mai rifiutata per il saldo.

Idempotency-Key (da 8 a 200 caratteri) risponde al nuovo tentativo di un mittente con la prima ricevuta per ventiquattro ore. Al massimo 120 invii al minuto per trigger.

Il controllo che Trello fa su un nuovo webhook. Risponde 200 senza corpo per un trigger il cui handshake è trello, e l’unico 404 not_found per ogni altro trigger, indirizzo e richiesta, così un’anteprima di link non apprende nulla. Non scrive nulla, non viene mai fatturato e non consuma budget di frequenza; il controllo a cui si è risposto compare nel registro delle consegne con l’esito handshake.

Ogni GET risponde il 404 e non legge nulla.

Gli invii a un trigger di sovrapposizione negli ultimi sette giorni, dal più recente (al massimo 100), con quando è arrivato ciascuno, come si è concluso ciascuno (shown, updated, unchanged, ended, ignored, refused, invalid o handshake), perché uno rifiutato o non valido lo è stato (credentials, signature, signature_missing, signature_invalid, timestamp_missing, timestamp_stale, secret_pending, handshake_invalid, disabled, body, mapping, field, rate_limited, payment_required, internal), lo stato, la dimensione, il numero di parti di file che un invio multipart portava (ignorate) e l’ID della richiesta.

Non conserva corpo, intestazione né credenziali. Un trigger CAP non ne ha.