API de Notificaciones

Lista las notificaciones de la organización que cubren el proyecto, de todos los canales, de la más antigua a la más reciente (máximo 50). status, failing_since, last_success_at y last_failure_at son los de este proyecto. El secreto de firma de un webhook nunca se devuelve aquí.

Requiere la capacidad de proyecto; una credencial solo de informes se rechaza con 403 forbidden, porque la respuesta incluye las URL de los receptores y los destinatarios.

Crea una notificación. channel email envía a recipients (owner, o user_ids de los miembros del proyecto); channel webhook hace POST, firmado, a url, que sigue las reglas de URL de webhook (https en un host de Internet público, puerto 443 u 8443, de lo contrario webhook_url_rejected). conditions lista los cambios de estado de pantalla en los que se activa; una notificación por correo necesita al menos uno, un webhook necesita conditions o event_types. screen_tags limita conditions a las pantallas que llevan cualquiera de esas etiquetas; vacío significa todas las pantallas, o audience indica qué pantallas con las reglas de una audiencia de campaña. min_severity y severity filtran y califican los avisos, y active_hours los retiene o descarta fuera de sus ventanas.

Una condición solo notifica después de haber durado hold_minutes (10 por defecto), y sigue un aviso de resolución cuando se resuelve después de haberse enviado un aviso. La notificación cubre solo este proyecto; una organización tiene como máximo 50 notificaciones, sin contar las predeterminadas que crea el sistema (notification_limit_reached).

El servidor genera el secreto de firma de un webhook y lo devuelve solo en esta respuesta y en rotate-secret; guárdelo. Un reintento exacto con la misma Idempotency-Key devuelve esta misma respuesta, secreto incluido, durante veinticuatro horas. Los avisos empiezan con el primer evento posterior a notification.created.

Requiere la capacidad de proyecto; una credencial solo de informes se rechaza con 403 forbidden, porque la respuesta incluye la URL del receptor o los destinatarios.

Cambia cualquiera de description (vacío la borra), conditions, screen_tags, audience, min_severity, severity, active_hours (null borra cada uno de estos), hold_minutes, recipients (email), url y event_types (webhook), destination y telegram_chat_id (Slack, Teams, PagerDuty y Telegram), enabled y snoozed_until; channel nunca cambia.

Un campo del otro canal es invalid_request. Una url nueva se comprueba como al crear.

Establecer enabled en true en una notificación deshabilitada borra su estado de fallo y empieza en el evento que registra el cambio; no se envía nada de lo ocurrido mientras estaba deshabilitada, y los avisos que seguían pendientes de antes de la deshabilitación se marcan como fallidos con webhook_disabled. snoozed_until no envía nada hasta ese instante (como máximo 30 días en el futuro; null finaliza la pausa); los avisos que corresponde enviar mientras tanto se omiten (snoozed).

Agrega notification.updated. If-Match protege la revisión. Aquí solo cambia una notificación que cubre únicamente este proyecto; una que cubre también otros proyectos de la organización es notification_covers_other_projects y se cambia desde la página Notificaciones de la organización.

Elimina la notificación y agrega notification.deleted. Sus avisos pendientes se marcan como fallidos con webhook_deleted; su registro de entregas ya no es accesible y caduca junto con la retención de eventos. Aquí solo se elimina una notificación que cubre únicamente este proyecto (notification_covers_other_projects en caso contrario).

Solo notificaciones de webhook (cualquier otro canal devuelve invalid_request). Reemplaza el secreto de firma y devuelve la notificación con el nuevo en secret; el secreto anterior deja de firmar de inmediato, y como máximo un intento que ya esté en tránsito aún puede llegar firmado con el anterior, por lo que acepte ambos durante un breve tiempo. Agrega notification.updated con details.changed [secret].

Un reintento exacto con la misma Idempotency-Key devuelve el mismo nuevo secreto por veinticuatro horas.

Agrega un evento de proyecto notification.test y pone en cola una entrega de ese evento solo para esta notificación (ninguna otra notificación recibe notification.test).

Un webhook recibe el evento como cuerpo; una notificación por correo envía un correo de prueba a sus destinatarios; una notificación de Slack, Teams o Telegram publica un mensaje de prueba; una notificación de PagerDuty activa un evento informativo y lo resuelve de inmediato.

Funciona en una notificación deshabilitada o en pausa, se intenta una sola vez sin reintentos y nunca cambia el estado de fallo de la notificación. Consulte el registro de entregas para ver su resultado.

El registro de entregas de la notificación, del evento más reciente al más antiguo. Una fila por evento, y por cada condición de ese evento en el caso de un aviso de pantalla; los reintentos actualizan la fila y GET .../deliveries/{delivery_id}/attempts lista sus intentos más recientes. Un aviso que nunca necesitó enviarse se omite con su motivo.

Las filas se conservan igual que los eventos (la retención de eventos del plan, como mínimo la ventana de reintentos de 24 horas). Devuelva next_cursor como before para obtener la página siguiente.

Los intentos de una entrega, del más reciente al más antiguo (los 20 más recientes), que se conservan junto con la fila de la entrega y por el mismo tiempo. Cada uno tiene su número de intento, cuándo terminó, el estado HTTP del receptor (null si ninguno respondió o para correo electrónico), la clase de error (null si tuvo éxito) y su duración.

Una entrega que no pertenece a esta notificación, o una notificación de otro proyecto, devuelve not_found.

Vuelve a enviar los correos de una notificación a una persona que los detuvo con el enlace para cancelar la suscripción de su correo (Notification.unsubscribed enumera a quienes lo hicieron). Idempotente: una persona que no está detenida no cambia nada, y la respuesta es la notificación tal como está.

Un cambio aumenta la revisión y agrega notification.updated con los detalles change resubscribed, user_id y via api. Una sesión del panel puede volver a suscribir a cualquier persona del proyecto; una credencial de agente necesita la capacidad de escritura del proyecto. La forma en que la propia persona vuelve es el botón Resubscribe de la página con la que responde su enlace para cancelar la suscripción.

El enlace en el pie de un correo de alerta. No lleva sesión ni bearer; el token t, creado por screenRIG para una notificación n y una persona u, es toda la autoridad, nunca vence y es válido mientras se conserve la versión de la clave de emisión que nombra.

La respuesta es una página que pide detener los correos de esa notificación para esa persona y que no cambia nada, de modo que un analizador de correo que abre el enlace no detiene nada; su botón envía a esta ruta. Una persona ya detenida ve una página cuyo botón la vuelve a suscribir.

Cualquier token, notificación o persona que no coincida, y una notificación que ya no existe o que no es por correo electrónico, recibe la misma página 404. La página no tiene scripts y solo envía a este origen. Máximo 30 solicitudes por minuto por dirección (rate_limited).

Detiene los correos de una notificación para la persona a la que está destinado el enlace. La consulta es la del enlace GET; el cuerpo no se lee, de modo que funcionan tanto la solicitud de un clic RFC 8058 de un proveedor de correo (List-Unsubscribe=One-Click, de los encabezados List-Unsubscribe y List-Unsubscribe-Post que lleva cada correo de alerta y de prueba) como el botón de la página.

Solo se detiene a esa persona, y solo para esa notificación; las demás siguen recibiendo correos, y la persona sigue en los destinatarios (recipients). Es idempotente. La primera vez aumenta la revisión y agrega notification.updated con los detalles change unsubscribed, user_id y via email_link.

La página con la que responde tiene un botón Resubscribe (POST /api/notifications/resubscribe); un miembro del proyecto ve a las personas detenidas en Notification.unsubscribed. Cuando no queda nadie a quien enviar correo, un aviso se omite como no_recipients. Cualquier enlace que no coincida recibe la página 404 del GET. Máximo 30 solicitudes por minuto por dirección (rate_limited).

Deshace POST /api/notifications/unsubscribe para la persona a la que está destinado el enlace: el botón Resubscribe de la página con la que responde. El mismo enlace, la misma autoridad y la misma página 404; idempotente. Un cambio aumenta la revisión y agrega notification.updated con los detalles change resubscribed, user_id y via email_link. Máximo 30 solicitudes por minuto por dirección (rate_limited).