API Notifiche

Elenca le notifiche dell’organizzazione che coprono il progetto, di ogni canale, dalla meno recente (al massimo 50). status, failing_since, last_success_at e last_failure_at sono quelli di questo progetto. Il segreto di firma di un webhook non viene mai restituito qui.

Richiede la capability project; una credenziale limitata ai report viene rifiutata con 403 forbidden, perché la risposta include gli URL di ricezione e i destinatari.

Crea una notifica. channel email invia a recipients (il proprietario, o gli user_ids dei membri del progetto); channel webhook esegue una POST firmata a url, che segue le regole degli URL webhook (https su un host Internet pubblico, porta 443 o 8443, altrimenti webhook_url_rejected). conditions elenca i cambi di stato dello schermo che la attivano; una notifica email ne richiede almeno uno, un webhook richiede conditions o event_types. screen_tags limita conditions agli schermi con uno qualsiasi di quei tag; vuoto significa ogni schermo, oppure audience indica quali schermi con le regole di un pubblico di campagna. min_severity e severity filtrano e valutano gli avvisi, e active_hours li trattiene o li scarta fuori dalle sue finestre.

Una condizione invia un avviso solo dopo essere durata per hold_minutes (predefinito 10), e quando si risolve dopo l’invio di un avviso ne segue uno di risoluzione. La notifica copre solo questo progetto; un’organizzazione ha al massimo 50 notifiche, escluse quelle predefinite create dal sistema (notification_limit_reached).

Il segreto di firma di un webhook viene generato dal server e restituito solo in questa risposta e in rotate-secret; conservalo. Un nuovo tentativo identico con la stessa Idempotency-Key restituisce questa stessa risposta, segreto incluso, per ventiquattro ore. Gli avvisi partono dal primo evento successivo a notification.created.

Richiede la capability project; una credenziale limitata ai report viene rifiutata con 403 forbidden, perché la risposta include l'URL di ricezione o i destinatari.

Modifica uno qualsiasi tra description (vuoto la azzera), conditions, screen_tags, audience, min_severity, severity, active_hours (null azzera ciascuno di questi), hold_minutes, recipients (email), url e event_types (webhook), destination e telegram_chat_id (Slack, Teams, PagerDuty e Telegram), enabled e snoozed_until; channel non cambia mai.

Un campo dell'altro canale è invalid_request. Un nuovo url viene controllato come in creazione.

Impostare enabled su true per una notifica disattivata ne cancella lo stato di errore e riparte dall'evento che registra la modifica; non viene inviato nulla relativo al periodo in cui era disattivata, e gli avvisi ancora in sospeso da prima della disattivazione vengono contrassegnati come falliti con webhook_disabled. snoozed_until non invia nulla fino a quell'istante (al massimo 30 giorni da adesso; null termina la sospensione); gli avvisi da inviare nel frattempo vengono saltati (snoozed).

Aggiunge notification.updated. If-Match protegge la revisione. Qui cambia solo una notifica che copre questo progetto soltanto; una che copre anche altri progetti dell’organizzazione è notification_covers_other_projects e si modifica dalla pagina Notifiche dell’organizzazione.

Elimina la notifica e aggiunge l’evento notification.deleted. I suoi avvisi in sospeso vengono contrassegnati come falliti con webhook_deleted; il suo registro delle consegne non è più consultabile e scade con il periodo di conservazione degli eventi. Qui viene eliminata solo una notifica che copre soltanto questo progetto (altrimenti notification_covers_other_projects).

Solo notifiche webhook (qualsiasi altro canale restituisce invalid_request). Sostituisce il segreto di firma e restituisce la notifica con quello nuovo in secret; il vecchio segreto smette di firmare subito, e al massimo un tentativo già in corso può ancora arrivare firmato con quello vecchio, quindi accetta entrambi per un breve periodo. Aggiunge l'evento notification.updated con details.changed [secret].

Un retry esatto con la stessa Idempotency-Key restituisce lo stesso nuovo segreto per ventiquattro ore.

Aggiunge un evento di progetto notification.test e mette in coda una consegna di tale evento solo a questa notifica (nessun'altra notifica riceve notification.test).

Un webhook riceve l’evento come corpo della richiesta; una notifica e-mail invia un’e-mail di prova ai destinatari; una notifica Slack, Teams o Telegram pubblica un messaggio di prova; una notifica PagerDuty attiva un evento informativo e lo risolve subito.

Funziona anche su una notifica disattivata o sospesa; la consegna viene tentata una sola volta senza nuovi tentativi e non modifica mai lo stato di errore della notifica. Interroga periodicamente il registro delle consegne per conoscerne l'esito.

Il registro delle consegne della notifica, dall'evento più recente. Una riga per evento e, per un avviso su uno schermo, una riga per ogni condizione di quell'evento; i nuovi tentativi aggiornano la riga e GET .../deliveries/{delivery_id}/attempts ne elenca i tentativi più recenti. Un avviso che non ha mai richiesto l'invio viene saltato con il relativo motivo.

Le righe vengono conservate come gli eventi (la conservazione degli eventi prevista dal piano, almeno la finestra di 24 ore per i nuovi tentativi). Rimanda next_cursor come in precedenza per la pagina successiva.

I tentativi di una consegna, dal più recente, gli ultimi 20, conservati con la riga della consegna e per lo stesso tempo. Ognuno riporta il numero di tentativo, quando è terminato, lo stato HTTP del server ricevente (null se nessuno ha risposto o per le e-mail), la classe di errore (null in caso di successo) e la durata.

Una consegna che non appartiene a questa notifica, o una notifica di un altro progetto, restituisce not_found.

Invia di nuovo le email di una notifica a una persona che le aveva interrotte con il link di annullamento dell’iscrizione nell’email (Notification.unsubscribed elenca chi lo ha fatto). Idempotente: una persona che non è interrotta non cambia nulla, e la risposta è la notifica così com’è.

Una modifica aumenta la revisione e aggiunge notification.updated con i dettagli change resubscribed, user_id e via api. Una sessione della dashboard può reiscrivere qualsiasi persona del progetto; una credenziale dell’agente richiede la capacità di scrittura del progetto. Il modo in cui la persona stessa torna indietro è il pulsante Resubscribe nella pagina con cui risponde il suo link di annullamento dell’iscrizione.

Il link nel piè di pagina di un’email di avviso. Non porta né sessione né bearer; il token t, creato da screenRIG per una notifica n e una persona u, è tutta l’autorità, non scade mai ed è valido finché la versione della chiave di emissione che nomina viene conservata.

La risposta è una pagina che chiede di interrompere le email di quella notifica per quella persona e che non cambia nulla, quindi uno scanner di posta che apre il link non interrompe nulla; il suo pulsante invia a questo percorso. Una persona già interrotta vede una pagina il cui pulsante la reiscrive.

Qualsiasi token, notifica o persona che non corrisponde, e una notifica eliminata o che non è via email, riceve la stessa pagina 404. La pagina non ha script e invia solo a questa origine. Al massimo 30 richieste al minuto per indirizzo (rate_limited).

Interrompe le email di una notifica per la persona a cui è destinato il link. La query è quella del link GET; il corpo non viene letto, quindi funzionano sia la richiesta a un clic RFC 8058 di un provider di posta (List-Unsubscribe=One-Click, dalle intestazioni List-Unsubscribe e List-Unsubscribe-Post che ogni email di avviso e di test porta) sia il pulsante della pagina.

Viene interrotta solo quella persona, e solo per quella notifica; gli altri continuano a ricevere le email, e la persona resta tra i destinatari (recipients). È idempotente. La prima volta aumenta la revisione e aggiunge notification.updated con i dettagli change unsubscribed, user_id e via email_link.

La pagina con cui risponde ha un pulsante Resubscribe (POST /api/notifications/resubscribe); un membro del progetto vede le persone interrotte in Notification.unsubscribed. Quando non resta nessuno a cui scrivere, un avviso viene saltato come no_recipients. Qualsiasi link che non corrisponde riceve la pagina 404 del GET. Al massimo 30 richieste al minuto per indirizzo (rate_limited).

Annulla POST /api/notifications/unsubscribe per la persona a cui è destinato il link: il pulsante Resubscribe della pagina con cui risponde. Stesso link, stessa autorità e stessa pagina 404; idempotente. Una modifica aumenta la revisione e aggiunge notification.updated con i dettagli change resubscribed, user_id e via email_link. Al massimo 30 richieste al minuto per indirizzo (rate_limited).