API Déclencheurs d’alerte

Liste les déclencheurs du projet (CAP et superposition), du plus ancien au plus récent (20 au plus), chacun avec son url d’ingestion, son username et sa dernière alerte ou son état de superposition. Aucun secret n’est jamais renvoyé ici.

Crée un déclencheur d’alerte CAP : une URL entrante à laquelle un système de notification d’urgence (Everbridge, Rave, Alertus, relais IPAWS et autres émetteurs CAP 1.2) poste des alertes, avec des identifiants HTTP Basic.

La réponse est le seul endroit où le mot de passe apparaît (avec la réponse de rotation) : stockez-le immédiatement dans le système d’envoi. target est une balise (chaque écran actif avec elle à l’arrivée de l’alerte) ou jusqu’à 500 screen_ids.

Une alerte prend le contrôle de chaque écran cible avec une liste de lecture par défaut jusqu’à l’alerte <expires>, sinon pour default_for_seconds (60 à 604800, défaut 3600) ; voir POST /api/triggers/{id}/cap. Une organisation a au maximum 20 déclencheurs, tous projets confondus (trigger_limit_reached). Ajoute trigger.created.

Une nouvelle tentative exacte avec la même Idempotency-Key retourne cette même réponse, mot de passe inclus, pendant vingt-quatre heures.

Le pull facultatif ajoute des sources CAP que la plateforme lit pour le déclencheur (voir CapPull) ; l’url d’ingestion continue de fonctionner à côté. kind overlay crée plutôt le second type : une url d’entrée (POST /api/triggers/{id}/overlay) où n’importe quel système (Home Assistant, une caméra, un outil d’alertes) publie quelques mots, affichés sur les écrans ciblés en bande par-dessus ce qui est diffusé (overlay.show bar, sur le bord inférieur ou supérieur) ou en prise de contrôle (overlay.show takeover) tant qu’une alerte dure ; voir TriggerOverlay.

Avec signing à true, la réponse porte aussi le secret de signature, une seule fois. verify fait authentifier un envoi par la signature propre d’un fournisseur (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana ou tout expéditeur HMAC) à la place du mot de passe, qui continue de fonctionner à côté ; il ne peut pas être combiné avec signing, et son secret est scellé et jamais renvoyé, seulement un indice. handshake nomme une poignée de main de fournisseur à laquelle l’URL répond (Microsoft Graph, monday.com, Trello ou Azure Event Grid ; verify slack et asana répondent à la leur).

Les maintiens de superposition durent de 10 à 604800 secondes (par défaut 600). Un déclencheur dont le sélecteur atteint un écran protégé donne protected_target (409), et un échec de lecture de la protection d’un écran donne dependency_unavailable (500, relancez la même requête) ; un déclencheur n’est pas disponible pour un appelant limité aux écrans.

Un déclencheur avec sa dernière alerte ou, pour un déclencheur de superposition, ses alertes actives (la plus récente en premier, la première s’affiche), les totaux de diffusion et l’indication du travail en attente. Une alerte dont until est passé est lue comme terminée avec ended_reason expired.

Modifie un déclencheur sans changer son URL ni son secret : label, target, default_for_seconds, le pull d’un déclencheur CAP (null le retire) et, pour un déclencheur de superposition, overlay.edge, style (remplace tout le style ; null l’efface), mapping (null le retire), enabled, signing, verify (null le retire ; sans secret, il conserve celui qui est stocké quand le fournisseur est le même) et handshake (null le retire).

Un déclencheur de superposition désactivé répond à son expéditeur par le même 404 qu’un mauvais secret. Activer la signature renvoie le secret de signature une seule fois dans cette réponse. Une bande se replace sur les nouveaux écrans cibles et le nouveau bord ; la nouvelle cible d’un déclencheur de prise de contrôle s’applique dès la prochaine alerte qui commence. Ajoute trigger.updated avec details.changed. If-Match protège la révision.

Chaque mise à jour est vérifiée sur la cible que le déclencheur aura, la nouvelle ou sinon celle qui est stockée : une cible qui atteint un écran protégé donne protected_target (409) quel que soit le membre qui modifie, et un échec de lecture de la protection d’un écran donne dependency_unavailable (500, relancez la même requête).

Supprime le déclencheur. Son URL cesse aussitôt de fonctionner, et sa liste de lecture d’alertes et ses images fixes (ou les bandes, la liste de lecture et la carte d’un déclencheur de superposition) sont supprimées. Un déclencheur qui affiche une alerte, ou en retire encore une, est refusé avec resource_conflict ; arrêtez-le d’abord. Ajoute trigger.deleted. If-Match protège la révision.

Remplace le mot de passe du déclencheur et renvoie le nouveau, une seule fois. L’ancien mot de passe cesse aussitôt de fonctionner ; mettez à jour le système expéditeur. Avec signing à true dans le corps, il remplace plutôt le secret de signature d’un déclencheur de superposition et renvoie celui-là, une seule fois (400 invalid_request quand le déclencheur ne signe pas). Ajoute trigger.updated avec details.rotated.

If-Match protège la révision.

Affiche une alerte d’exercice d’une minute (une carte bleue avec une bannière jaune EXERCISE) sur les écrans du déclencheur, exactement comme une alerte reçue, afin de vérifier le ciblage et les écrans sans le système d’envoi. Le refus resource_conflict survient pendant que le déclencheur affiche une alerte, donc un test ne remplace jamais une alerte réelle.

Une nouvelle tentative exacte avec la même Idempotency-Key donne l’outcome duplicate. Un déclencheur de superposition affiche l’alerte screenrig-test (label Test, title Test overlay) pendant une minute et répond par un TriggerOverlayReceipt.

Met fin à l’alerte du déclencheur (ended_reason cleared) et efface les prises de contrôle qu’il a définies. Un écran remplacé par une autre prise de contrôle depuis est laissé intact. Un déclencheur sans alerte active répond inchangé. Ajoute trigger.alert_received avec résultat ended.

Pour un déclencheur de superposition, le corps peut nommer une alerte (alert_id) ; sans cela, toutes les alertes prennent fin, et la fin de la dernière abaisse la bande ou termine les prises de contrôle.

L’URL à laquelle un système de notification d’urgence poste une alerte CAP 1.2 (tout type de contenu XML, au plus 256 KiB). Il s’authentifie avec les identifiants HTTP Basic du déclencheur : le nom d’utilisateur est l’ID du déclencheur, le mot de passe celui retourné par create ou rotate.

Un message avec le statut Actual ou Exercise et le type msgType Alert affiche une carte plein écran (titre, événement, description, instruction et expéditeur, rouge pour Extrême, Sévère ou sans gravité, ambre pour Modéré, bleu pour Mineur ; Exercise ajoute une bannière jaune EXERCISE) sur chaque écran cible avec une playlist par défaut, jusqu’à <expires>, sinon pendant default_for_seconds, au maximum 7 jours.

Une mise à jour qui référence l’alerte affichée la redessine sur place et déplace les prises de contrôle quand <expires> change. Un annule qui la référence, ou tout message avec responseType AllClear, la termine et efface les prises de contrôle qu’elle a définies. Un déclencheur affiche une alerte : une nouvelle alerte remplace celle affichée.

Les messages Test, Système et Brouillon, Ack et Erreur, une alerte déjà expirée, et une Annulation d’alerte non affichée sont ignorés ; le même expéditeur et identifiant deux fois est un doublon. La réponse est un accusé de réception nommant le résultat ; les écrans sont écrits juste après (alert.screens.pending).

Les prises de contrôle contournent les limites de fréquence de contrôle des écrans et ne sont jamais mesurées ni refusées pour solde insuffisant. Elles ajoutent trigger.alert_received.

L’URL où un système externe (Home Assistant, une caméra, un détecteur de porte, un outil d’alertes ou un fournisseur qui signe ses propres webhooks) publie pour que les écrans du déclencheur affichent quelques mots. Il s’authentifie avec le secret propre du déclencheur dans l’en-tête Authorization: Bearer <secret>, ou en HTTP Basic avec l’identifiant du déclencheur comme nom d’utilisateur.

Quand le déclencheur a été créé avec verify, une signature valide dans l’en-tête propre à ce fournisseur (voir WebhookVerifyWrite) authentifie l’envoi à la place du secret, qui continue de fonctionner à côté.

Quand le déclencheur signe, ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret> est aussi requis, et t doit se situer à moins de cinq minutes de l’horloge du serveur.

Un déclencheur inconnu, un déclencheur CAP, un secret ou une signature faux ou absents, un horodatage périmé, un déclencheur désactivé et chaque GET reçoivent le même 404 not_found ; le projet voit la raison dans le journal de livraison du déclencheur.

Un déclencheur configuré pour une poignée de main de fournisseur y répond en premier, avant qu’aucun identifiant ne soit demandé, à une requête qui est cette poignée de main : le défi url_verification de Slack (signé), le validationToken de Microsoft Graph, le X-Hook-Secret d’Asana (conservé scellé comme secret de signature de ses événements), le challenge de monday.com, le SubscriptionValidationEvent d’Azure Event Grid et la vérification HEAD de Trello (l’opération head de cette URL).

Une poignée de main ne change aucune alerte, n’est jamais facturée et ne consomme aucun budget de débit, et elle est consignée dans le journal de livraison avec le résultat handshake.

Le corps, de 256 KiB au plus, est du JSON, du application/x-www-form-urlencoded ou du multipart/form-data (chaque champ de texte est body.<field>, les parties de fichier sont ignorées et comptées dans le journal de livraison) ; avec un mapping, le gabarit construit la requête à partir de body et de query. alert_id nomme l’alerte : un envoi dont l’identifiant est actif met à jour cette alerte au lieu d’en empiler une autre, et l’alerte la plus récente s’affiche.

Chaque déclenchement ou mise à jour retient son alerte pendant duration à partir de cet envoi (de 10 à 604800 secondes, ou 10s, 5m, 2h, 1d, ou until_cleared ; par défaut celle du déclencheur), de sorte qu’un capteur qui continue d’envoyer garde la superposition affichée.

Un envoi avec clear à true, ou un state qui signifie que c’est terminé (off, closed, clear, cleared, resolved, ok, normal, inactive, ended), met fin à l’alerte portant cet identifiant, ou à toutes les alertes s’il n’y en a pas. Un déclenchement ou une mise à jour compte pour une requête d’API facturée ; un arrêt est gratuit et n’est jamais refusé faute de solde.

Idempotency-Key (de 8 à 200 caractères) répond à la nouvelle tentative d’un expéditeur par le premier reçu pendant vingt-quatre heures. Au plus 120 envois par minute par déclencheur.

La vérification que Trello fait d’un nouveau webhook. Elle répond 200 sans corps pour un déclencheur dont la poignée de main est trello, et le seul 404 not_found pour tout autre déclencheur, adresse et requête : un aperçu de lien n’apprend donc rien. Elle n’écrit rien, n’est jamais facturée et ne consomme aucun budget de débit ; la vérification traitée figure dans le journal de livraison avec le résultat handshake.

Chaque GET répond le 404 et ne lit rien.

Les envois vers un déclencheur de superposition au cours des sept derniers jours, du plus récent au plus ancien (au plus 100), avec le moment où chacun est arrivé, la façon dont chacun s’est terminé (shown, updated, unchanged, ended, ignored, refused, invalid ou handshake), la raison pour laquelle un envoi refusé ou invalide l’a été (credentials, signature, signature_missing, signature_invalid, timestamp_missing, timestamp_stale, secret_pending, handshake_invalid, disabled, body, mapping, field, rate_limited, payment_required, internal), le statut, la taille, le nombre de parties de fichier qu’un envoi multipart portait (ignorées) et l’ID de requête.

Il ne conserve ni corps, ni en-tête, ni identifiant. Un déclencheur CAP n’en a aucune.