API de Disparadores de alerta

Lista los activadores del proyecto (CAP y de superposición), del más antiguo al más reciente (20 como máximo), cada uno con su url de ingesta, su username y su última alerta o estado de superposición. Aquí nunca se devuelve ningún secreto.

Crea un disparador de alerta CAP: una URL entrante a la que un sistema de notificaciones de emergencia (Everbridge, Rave, Alertus, relés IPAWS y otros emisores CAP 1.2) envía alertas, con credenciales HTTP Basic.

La respuesta es el único lugar donde aparece la contraseña (con la respuesta de rotación): guárdela en el sistema de envío de inmediato. target es una etiqueta (todas las pantallas activas con ella cuando llega la alerta) o hasta 500 screen_ids.

Una alerta toma todas las pantallas objetivo con una lista de reproducción predeterminada hasta que la alerta <expires>, o para default_for_seconds (60 a 604800, por defecto 3600); vea POST /api/triggers/{id}/cap. Una organización tiene como máximo 20 disparadores en todos sus proyectos (trigger_limit_reached). Añade trigger.created.

Un reintento exacto con la misma Idempotency-Key devuelve esta misma respuesta, incluida la contraseña, por veinticuatro horas.

El pull opcional añade fuentes CAP que la plataforma lee para el activador (véase CapPull); la url de ingesta sigue funcionando a su lado. kind overlay crea en su lugar el segundo tipo: una url de entrada (POST /api/triggers/{id}/overlay) en la que cualquier sistema (Home Assistant, una cámara, una herramienta de alertas) publica unas pocas palabras, que se muestran en las pantallas de destino como una franja sobre lo que se reproduce (overlay.show bar, en el borde inferior o superior) o como una toma de control (overlay.show takeover) mientras dura una alerta; véase TriggerOverlay.

Con signing true la respuesta también lleva el secreto de firma una vez. verify hace que la firma propia de un proveedor (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana o cualquier remitente HMAC) autentique un envío en lugar de la contraseña, que sigue funcionando a su lado; no puede combinarse con signing, y su secreto se sella y nunca se devuelve, solo una pista. handshake nombra un handshake de proveedor al que responde la URL (Microsoft Graph, monday.com, Trello o Azure Event Grid; verify slack y asana responden al suyo).

Las retenciones de superposición son de 10 a 604800 segundos (predeterminado 600). Un activador cuyo selector alcanza una pantalla protegida es protected_target (409), y una lectura fallida de la protección de pantallas es dependency_unavailable (500, repita la misma solicitud); un activador no está disponible para un llamador limitado a pantallas.

Un activador con su última alerta o, en un activador de superposición, sus alertas activas (la más reciente primero, la primera se muestra), los recuentos de difusión y si hay trabajo pendiente. Una alerta pasada su until se lee como terminada con ended_reason expired.

Cambia un activador sin cambiar su URL ni su secreto: label, target, default_for_seconds, el pull de un activador CAP (null lo quita) y, en un activador de superposición, overlay.edge, style (reemplaza todo el estilo; null lo borra), mapping (null lo quita), enabled, signing, verify (null lo quita; sin secreto conserva el almacenado cuando el proveedor es el mismo) y handshake (null lo quita).

Un activador de superposición desactivado responde a su remitente con el mismo 404 que un secreto incorrecto. Activar la firma devuelve el secreto de firma una sola vez en esta respuesta. Una franja se recoloca en las nuevas pantallas de destino y en el nuevo borde; el nuevo destino de un activador de toma de control se aplica desde la siguiente alerta que empiece. Añade trigger.updated con details.changed. If-Match protege la revisión.

Cada actualización se comprueba sobre el destino que tendrá el activador, el nuevo o, si no, el guardado: un destino que alcanza una pantalla protegida es protected_target (409) sea cual sea el miembro que cambia, y una lectura fallida de la protección de pantallas es dependency_unavailable (500, repita la misma solicitud).

Elimina el activador. Su URL deja de funcionar de inmediato, y se eliminan su lista de reproducción de alertas y sus imágenes fijas (o las franjas, la lista de reproducción y la tarjeta de un activador de superposición). Un activador que muestra una alerta, o que aún está retirando una, se rechaza con resource_conflict; termínelo primero. Añade trigger.deleted. If-Match protege la revisión.

Reemplaza la contraseña del activador y devuelve la nueva, una sola vez. La contraseña anterior deja de funcionar de inmediato; actualice el sistema remitente. Con signing en true en el cuerpo, reemplaza en su lugar el secreto de firma de un activador de superposición y devuelve ese, una sola vez (400 invalid_request cuando el activador no firma). Añade trigger.updated con details.rotated.

If-Match protege la revisión.

Muestra una alerta de ejercicio de un minuto (una tarjeta azul con un banner amarillo EXERCISE) en las pantallas del disparador, exactamente como lo haría una alerta recibida, para que se pueda verificar la orientación y las pantallas sin el sistema de envío. Se rechazó resource_conflict mientras el disparador muestra una alerta, por lo que una prueba nunca reemplaza una real.

Un reintento exacto con la misma Idempotency-Key responde con outcome duplicate. Un activador de superposición muestra la alerta screenrig-test (label Test, title Test overlay) durante un minuto y responde con un TriggerOverlayReceipt.

Finaliza la alerta del disparador (ended_reason cleared) y elimina las tomas de control que estableció. Una pantalla que otra toma de control haya reemplazado desde entonces queda intacta. Un disparador sin alerta activa responde sin cambios. Añade trigger.alert_received con resultado ended.

En un activador de superposición, el cuerpo puede nombrar una alerta (alert_id); sin ella terminan todas las alertas, y al terminar la última se baja la franja o se terminan las tomas de control.

La URL a la que un sistema de notificación de emergencia publica una alerta CAP 1.2 (cualquier tipo de contenido XML, máximo 256 KiB). Se autentica con las credenciales HTTP Basic propias del disparador: el nombre de usuario es el id del disparador, la contraseña la devuelta por create o rotate.

Un mensaje con estado Actual o Ejercicio y msgType Alerta muestra una tarjeta a pantalla completa (título, evento, descripción, instrucción y remitente, rojo para Extremo, Severo o sin severidad, ámbar para Moderado, azul para Menor; Ejercicio añade un banner amarillo EJERCICIO) en cada pantalla objetivo con una lista de reproducción predeterminada, hasta <expires>, o para default_for_seconds, como máximo 7 días.

Una actualización que referencia la alerta mostrada la redibuja en su lugar y mueve las tomas cuando <expires> cambió. Una cancelación que la referencia, o cualquier mensaje con responseType AllClear, la termina y limpia las tomas que estableció. Un disparador muestra una alerta: una nueva alerta reemplaza a la mostrada.

Los mensajes de prueba, sistema y borrador, Ack y Error, una alerta ya expirada y una Cancelación de alerta no mostrada se ignoran; el mismo remitente e identificador dos veces es un duplicado. La respuesta es un recibo que nombra el resultado; las pantallas se escriben justo después (alert.screens.pending).

Los takeovers evaden los límites de tasa de control de pantalla y nunca se miden ni se rechazan por saldo. Añade trigger.alert_received.

La URL en la que un sistema externo (Home Assistant, una cámara, un sensor de puerta, una herramienta de alertas o un proveedor que firma sus propios webhooks) publica para que las pantallas del activador muestren unas pocas palabras. Se autentica con el secreto propio del activador en el encabezado Authorization: Bearer <secret>, o con HTTP Basic usando el id del activador como usuario.

Cuando el activador se creó con verify, una firma válida en el encabezado propio de ese proveedor (vea WebhookVerifyWrite) autentica el envío en lugar del secreto, que sigue funcionando a su lado.

Cuando el activador firma, también se exige ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret>, y t debe estar a menos de cinco minutos del reloj del servidor.

Un activador desconocido, un activador CAP, un secreto o una firma incorrectos o ausentes, una marca de tiempo obsoleta, un activador desactivado y cada GET reciben el mismo 404 not_found; el proyecto ve el motivo en el registro de entregas del activador.

Un activador configurado para un handshake de proveedor lo responde primero, antes de pedir ninguna credencial, a una solicitud que es ese handshake: el desafío url_verification de Slack (firmado), el validationToken de Microsoft Graph, el X-Hook-Secret de Asana (guardado sellado como secreto de firma de sus eventos), el challenge de monday.com, el SubscriptionValidationEvent de Azure Event Grid y la comprobación HEAD de Trello (la operación head de esta URL).

Un handshake no cambia ninguna alerta, nunca se factura y no gasta presupuesto de velocidad, y se registra en el registro de entregas con el resultado handshake.

El cuerpo, de 256 KiB como máximo, es JSON, application/x-www-form-urlencoded o multipart/form-data (cada campo de texto es body.<field>, las partes de archivo se ignoran y se cuentan en el registro de entregas); con un mapping, la plantilla construye la solicitud a partir de body y query. alert_id nombra la alerta: un envío con un id activo actualiza esa alerta en lugar de apilar otra, y se muestra la alerta iniciada más recientemente.

Cada activación o actualización mantiene su alerta durante duration desde ese envío (de 10 a 604800 segundos, o 10s, 5m, 2h, 1d, o until_cleared; por defecto el del activador), de modo que un sensor que sigue enviando mantiene la superposición.

Un envío con clear en true, o un state que significa que terminó (off, closed, clear, cleared, resolved, ok, normal, inactive, ended), termina la alerta con ese id, o todas las alertas si no se indica ninguno. Una activación o actualización es una solicitud de API facturada; una finalización es gratuita y nunca se rechaza por saldo.

Idempotency-Key (de 8 a 200 caracteres) responde al reintento de un remitente con el primer recibo durante veinticuatro horas. Como máximo 120 envíos por minuto por activador.

La comprobación que hace Trello de un webhook nuevo. Responde 200 sin cuerpo para un activador cuyo handshake es trello, y el único 404 not_found para cualquier otro activador, dirección y solicitud, así que una vista previa de enlace no aprende nada. No escribe nada, nunca se factura y no gasta presupuesto de velocidad; la comprobación respondida figura en el registro de entregas con el resultado handshake.

Cada GET responde el 404 y no lee nada.

Los envíos a un activador de superposición durante los últimos siete días, los más recientes primero (como máximo 100), con cuándo llegó cada uno, cómo terminó cada uno (shown, updated, unchanged, ended, ignored, refused, invalid o handshake), por qué lo fue uno rechazado o no válido (credentials, signature, signature_missing, signature_invalid, timestamp_missing, timestamp_stale, secret_pending, handshake_invalid, disabled, body, mapping, field, rate_limited, payment_required, internal), el estado, el tamaño, el número de partes de archivo que llevaba un envío multipart (ignoradas) y el ID de solicitud.

No guarda cuerpo, cabecera ni credencial. Un activador CAP no tiene ninguna.