Benachrichtigungen-API

Listet die Benachrichtigungen der Organisation, die das Projekt abdecken, alle Kanäle, älteste zuerst (höchstens 50). status, failing_since, last_success_at und last_failure_at sind die dieses Projekts. Das Signing-Secret eines Webhooks wird hier nie zurückgegeben.

Erfordert die Projekt-Berechtigung; ein Token nur für Berichte wird mit 403 forbidden abgelehnt, weil die Antwort Empfänger-URLs und Empfänger enthält.

Erstellt eine Benachrichtigung. Der Kanal email sendet an recipients (Inhaber oder user_ids der Mitglieder des Projekts); der Kanal webhook sendet per POST, signiert, an url, die den Webhook-URL-Regeln folgt (https auf einem öffentlichen Internet-Host, Port 443 oder 8443, sonst webhook_url_rejected). conditions listet die Änderungen des Bildschirmstatus, bei denen sie auslöst; eine E-Mail-Benachrichtigung braucht mindestens eine, ein Webhook braucht conditions oder event_types. screen_tags beschränkt conditions auf Bildschirme mit einem beliebigen dieser Tags; leer bedeutet jeden Bildschirm, oder audience bestimmt die Bildschirme mit den Regeln einer Kampagnen-Zielgruppe. min_severity und severity filtern und bewerten die Meldungen, und active_hours hält sie außerhalb seiner Fenster zurück oder verwirft sie.

Eine Bedingung benachrichtigt erst, nachdem sie hold_minutes lang bestanden hat (standardmäßig 10); endet sie, nachdem eine Meldung versandt wurde, folgt eine Behebungsmeldung. Die Benachrichtigung deckt allein dieses Projekt ab; eine Organisation hat höchstens 50 Benachrichtigungen, die vom System angelegten Standardbenachrichtigungen nicht mitgezählt (notification_limit_reached).

Das Signing-Secret eines Webhooks wird vom Server erzeugt und nur in dieser Antwort und in rotate-secret zurückgegeben; speichern Sie es. Eine exakte Wiederholung mit demselben Idempotency-Key liefert vierundzwanzig Stunden lang dieselbe Antwort, Secret eingeschlossen. Meldungen beginnen mit dem ersten Ereignis nach notification.created.

Erfordert die Projekt-Berechtigung; ein Token nur für Berichte wird mit 403 forbidden abgelehnt, weil die Antwort die Empfänger-URL oder Empfänger enthält.

Ändert beliebige von description (leer löscht sie), conditions, screen_tags, audience, min_severity, severity, active_hours (null löscht jeweils diese), hold_minutes, recipients (E-Mail), url und event_types (Webhook), destination und telegram_chat_id (Slack, Teams, PagerDuty und Telegram), enabled und snoozed_until; channel ändert sich nie.

Ein Feld des anderen Kanals ist invalid_request. Eine neue url wird wie beim Erstellen geprüft.

Wird enabled bei einer deaktivierten Benachrichtigung auf true gesetzt, wird ihr Fehlerzustand gelöscht und sie beginnt bei dem Ereignis, das die Änderung festhält; nichts aus der Zeit, in der sie aus war, wird gesendet, und Meldungen, die vor der Deaktivierung noch ausstanden, werden mit webhook_disabled als fehlgeschlagen markiert. snoozed_until sendet bis zu diesem Zeitpunkt nichts (höchstens 30 Tage im Voraus; null beendet die Stummschaltung); Meldungen, die in der Zwischenzeit fällig werden, werden übersprungen (snoozed).

Hängt notification.updated an. If-Match schützt die Revision. Hier ändert sich nur eine Benachrichtigung, die allein dieses Projekt abdeckt; eine, die auch andere Projekte der Organisation abdeckt, ist notification_covers_other_projects und wird auf der Seite Benachrichtigungen der Organisation geändert.

Löscht die Benachrichtigung und hängt notification.deleted an. Ihre ausstehenden Meldungen werden mit webhook_deleted als fehlgeschlagen markiert; ihr Zustellungsprotokoll ist nicht mehr adressierbar und läuft mit der Ereignisaufbewahrung ab. Hier wird nur eine Benachrichtigung gelöscht, die allein dieses Projekt abdeckt (sonst notification_covers_other_projects).

Nur Webhook-Benachrichtigungen (jeder andere Kanal ergibt invalid_request). Ersetzt das Signing-Secret und gibt die Benachrichtigung mit dem neuen in secret zurück; das alte Secret signiert sofort nicht mehr, und höchstens ein bereits laufender Versuch kann noch mit dem alten signiert eintreffen, akzeptieren Sie daher kurzzeitig beide. Hängt notification.updated mit details.changed [secret] an.

Ein exakter Wiederholungsversuch mit demselben Idempotency-Key gibt dasselbe neue Geheimnis für vierundzwanzig Stunden zurück.

Hängt ein Projektereignis notification.test an und stellt eine Zustellung davon nur an diese Benachrichtigung in die Warteschlange (keine andere Benachrichtigung erhält notification.test).

Ein Webhook erhält das Ereignis als Anfragetext; eine E-Mail-Benachrichtigung sendet eine Test-E-Mail an ihre Empfänger; eine Slack-, Teams- oder Telegram-Benachrichtigung postet eine Testnachricht; eine PagerDuty-Benachrichtigung löst ein Informationsereignis aus und behebt es sofort.

Der Aufruf funktioniert bei einer deaktivierten oder stummgeschalteten Benachrichtigung, wird einmal ohne Wiederholungen versucht und ändert nie den Fehlerzustand der Benachrichtigung. Fragen Sie das Zustellungsprotokoll nach dem Ergebnis ab.

Das Zustellungsprotokoll der Benachrichtigung, neuestes Ereignis zuerst. Eine Zeile pro Ereignis und, bei einer Bildschirmmeldung, pro Bedingung dieses Ereignisses; Wiederholungen aktualisieren die Zeile, und GET .../deliveries/{delivery_id}/attempts listet ihre jüngsten Versuche auf. Eine Meldung, die nie gesendet werden musste, wird mit ihrem Grund übersprungen.

Zeilen werden wie Ereignisse aufbewahrt (die Ereignisaufbewahrung des Tarifs, mindestens das 24-Stunden-Fenster für Wiederholungen). Übergeben Sie next_cursor wie zuvor zurück, um die nächste Seite zu erhalten.

Die Versuche einer Zustellung, neueste zuerst, die letzten 20, aufbewahrt zusammen mit der Zustellungszeile und ebenso lange. Jeder hat seine Versuchsnummer, den Zeitpunkt seines Endes, den HTTP-Status des Empfängers (null, wenn keiner geantwortet hat oder bei E-Mail), die Fehlerklasse (null bei Erfolg) und seine Dauer.

Bei einer Zustellung, die nicht zu dieser Benachrichtigung gehört, oder einer Benachrichtigung eines anderen Projekts lautet die Antwort not_found.

Schickt einer Person wieder die E-Mails einer Benachrichtigung, nachdem sie diese mit dem Abmeldelink in der E-Mail beendet hatte (Notification.unsubscribed listet auf, wer das getan hat). Idempotent: Eine Person, die nicht abgemeldet ist, ändert nichts, und die Antwort ist die Benachrichtigung, wie sie ist.

Eine Änderung erhöht die Revision und hängt notification.updated mit den Details change resubscribed, user_id und via api an. Eine Dashboard-Sitzung darf jede Person des Projekts wieder anmelden; ein Agenten-Zugangsdatum braucht die Schreibberechtigung für das Projekt. Den eigenen Weg zurück hat die Person über die Schaltfläche Resubscribe auf der Seite, mit der ihr Abmeldelink antwortet.

Der Link in der Fußzeile einer Alarm-E-Mail. Er trägt weder eine Sitzung noch ein Bearer-Token; das Token t, von screenRIG für eine Benachrichtigung n und eine Person u erzeugt, ist die gesamte Berechtigung, läuft nie ab und gilt, solange die Ausstellungsschlüsselversion, die es nennt, aufbewahrt wird.

Die Antwort ist eine Seite, die fragt, ob die E-Mails dieser Benachrichtigung für diese Person beendet werden sollen, und nichts ändert; ein Mail-Scanner, der den Link öffnet, beendet also nichts. Ihre Schaltfläche sendet an diesen Pfad. Eine bereits abgemeldete Person sieht eine Seite, deren Schaltfläche sie wieder anmeldet.

Jedes nicht passende Token, jede nicht passende Benachrichtigung oder Person sowie eine gelöschte oder nicht per E-Mail versendete Benachrichtigung bekommt dieselbe 404-Seite. Die Seite enthält kein Skript und sendet nur an diesen Ursprung. Höchstens 30 Anfragen pro Minute und Adresse (rate_limited).

Beendet die E-Mails einer Benachrichtigung für die Person, für die der Link bestimmt ist. Die Abfrage ist die des GET-Links; der Body wird nicht gelesen, sodass sowohl die One-Click-Anfrage eines Mail-Anbieters nach RFC 8058 (List-Unsubscribe=One-Click, aus den Headern List-Unsubscribe und List-Unsubscribe-Post jeder Alarm- und Test-E-Mail) als auch die Schaltfläche der Seite funktionieren.

Nur diese Person wird abgemeldet, und nur für diese Benachrichtigung; die anderen erhalten weiter E-Mails, und die Person bleibt unter den Empfängern (recipients). Der Aufruf ist idempotent. Beim ersten Mal erhöht er die Revision und hängt notification.updated mit den Details change unsubscribed, user_id und via email_link an.

Die Seite, mit der sie antwortet, hat eine Schaltfläche Resubscribe (POST /api/notifications/resubscribe); ein Projektmitglied sieht die abgemeldeten Personen in Notification.unsubscribed. Bleibt niemand mehr übrig, wird eine Meldung als no_recipients übersprungen. Jeder nicht passende Link bekommt die 404-Seite des GET. Höchstens 30 Anfragen pro Minute und Adresse (rate_limited).

Macht POST /api/notifications/unsubscribe für die Person rückgängig, für die der Link bestimmt ist: die Schaltfläche Resubscribe der Seite, mit der dieser Aufruf antwortet. Derselbe Link, dieselbe Berechtigung und dieselbe 404-Seite; idempotent. Eine Änderung erhöht die Revision und hängt notification.updated mit den Details change resubscribed, user_id und via email_link an. Höchstens 30 Anfragen pro Minute und Adresse (rate_limited).