Integrations-API

Restow liefert von Tag eins an in jeder Edition eine dokumentierte REST-API unter /api/v1, mit OpenAPI-Beschreibung: Sie ist keine kostenpflichtige Zusatzfunktion. Sie dient dazu, Restow an die Werkzeuge anzubinden, die ein MSP oder eine IT-Abteilung bereits einsetzt: RMM, PSA und Ticketsysteme. Wo die maschinenlesbare Beschreibung und die Betriebs-Endpunkte liegen, steht unter Referenz → API-Referenz.

Was sie abdeckt

Sicherungs-, Restore- und Verify-Status sowie die zugrunde liegenden Jobs (mit einem Server-Sent-Events-Stream für Live-Fortschritt).
Geschützte Objekte: Postfächer, OneDrives, IMAP-Konten und, seit 0.4.0, SharePoint-Websites (Art site) und, seit 0.4.5, Kalender und Unterhaltungen von Microsoft-365-Gruppen (Art group), mit ihrem letzten Snapshot und ihrem Status (active, excluded oder orphaned; seit 0.4.7 kann ein orphaned Objekt noch an seiner Quelle stehen, siehe Vertrag 1.7.0).
Speicherziele und deren Zustand.
Server und Clients, die der Agent sichert (GET /api/v1/endpoints), siehe Server und Clients.
Freigaben (SMB und NFS) und Proxmox-VE-Gäste als Zahlen in GET /api/v1/status, siehe Freigaben und belegte Bytes.
Archiv-Status und -Nachweise: Eingang je Erfassungsweg (Exchange-Journaling, Graph, IMAP-Archivierung, Datei-Import; weitergeleitete Kopien zählen nur in den Gesamtzahlen, siehe Archiv-Erfassung), Prüfung der Hash-Kette, Aufbewahrung und Legal Holds sowie ein Nachweisbericht für einen Zeitraum als JSON (ein signiertes PDF wird nicht erzeugt; siehe Archivierung).
Die laufende Version und ob ein Update verfügbar ist, siehe Version und Updates.
Eine Directory je Mandant: eine saubere Aufstellung von Nutzern und Postfächern, gedacht zur Weitergabe an ein PSA für Abrechnung oder Asset-Tracking.
Webhooks (siehe unten).

API-Schlüssel und Berechtigungen

Legen Sie Schlüssel unter Integrationen → API-Schlüssel an. Jeder Schlüssel gehört zu einem Mandanten, hat einen Namen (sichtbar in der Schlüsselliste und im Audit-Log), einen optionalen Ablauf (30/90/180/365 Tage oder nie) und nur die Berechtigungen, die er braucht. Berechtigungen schließen einander nicht ein: Ein Schlüssel, der den Schutz ändert, braucht also zusätzlich Lesezugriff, wenn er auch Nutzer liest. Der vollständige Umfang:

Berechtigung	Gewährt
`status:read`	Zusammenfassung, Speicher, letzter Verify-Bericht, Server und Clients (Endpoints), laufende Version.
`jobs:read`	Jobs mit Fortschritt, Fehlern und Dauer.
`items:read`	Geschützte Objekte mit ihrem letzten Snapshot.
`users:read`	Die Nutzer-/Postfach-Directory, für PSA-Abgleich und Abrechnung.
`archive:read`	Archiv-Status, Erfassungswege, Kettenprüfung und der Nachweisbericht.
`restore:write`	Sicherungen und Wiederherstellungen starten.
`verify:write`	Verify-Läufe starten (stichprobenartige Rücklese-Prüfungen).
`users:write`	Nutzer ein- oder ausschließen, z. B. beim On- und Offboarding.
`webhooks:manage`	Webhooks dieses Mandanten anlegen, ändern und löschen.

Ein Schlüssel authentifiziert sich als Authorization: Bearer <Schlüssel> und ist auf 600 Anfragen je 10 Minuten begrenzt. Restow zeigt den Wert des Schlüssels einmal, bei der Erstellung. Gespeichert wird nur ein Fingerabdruck, ein verlorener Schlüssel lässt sich also nicht wiederherstellen, nur widerrufen und ersetzen. Der Widerruf ist sofort und unumkehrbar; der Eintrag bleibt für den Prüfpfad in der Liste.

Die Service-Provider-Edition bietet zusätzlich Provider-Schlüssel: Sie wirken über jeden vom Provider verwalteten Mandanten hinweg (Anfragen nennen den Mandanten mit einem X-Restow-Tenant-Header), für einen einzigen Integrationspunkt über alle Kunden hinweg. Sie brauchen die vollständigen Images mit einem Lizenzschlüssel Service Provider: Ohne ihn wird das Anlegen eines Provider-Schlüssels mit 403 abgelehnt (urn:restow:problem:edition-required in den vollständigen Images, urn:restow:problem:feature-unavailable in den Community-Images).

Server und Clients

GET /api/v1/endpoints listet die Server und Clients auf, die der Restow-Agent sichert (Endpoint-Backup), für die Asset-Liste eines RMM oder die Abrechnung je Rechner. Der Aufruf braucht die Berechtigung status:read, nimmt optional profile=server oder profile=client entgegen und ist nicht seitenweise: Die Antwort ist { "items": [...], "total": n }. Jeder Lesezugriff wird wie die übrigen Lesezugriffe auditiert. Jeder Eintrag hat:

Feld	Bedeutung
`id`, `hostname`, `displayName`	Der Rechner.
`profile`	`server` oder `client`.
`os`, `arch`	Das System (heute `linux` oder `darwin` für macOS) und die CPU-Architektur (`amd64` oder `arm64`).
`agentVersion`, `status`	Die Version des Agents sowie `active` oder `revoked`.
`connection`	`online`, wenn sich der Agent innerhalb von 15 Minuten gemeldet hat, sonst `offline`, oder `never`.
`lastSeenAt`, `lastBackupAt`, `lastSuccessAt`	Der letzte Kontakt, das Ende des letzten Sicherungslaufs unabhängig vom Ergebnis und das Ende der letzten Sicherung, die einen Snapshot erzeugt hat.
`readiness`	`state` (`green`, `yellow`, `red`, `unverified` oder `no_backup`), `checkedAt` und `overdue`. Ein Rechner ist erst `green`, wenn ein Restore-Test seiner neuesten Sicherung, der Stichproben-Dateien zurückliest, jeden Stichproben-Hash bestätigt hat.
`attention`	Warum der Rechner einen Blick braucht: `silent`, `backup_overdue`, `last_backup_failed`, `restore_test_failed`, `repository_damaged` oder `never_seen`.
`createdAt`	Wann der Rechner in Restow angelegt wurde.

GET /api/v1/status enthält außerdem ein Objekt endpoints mit den Zahlen total, servers, clients, revoked, needingAttention und lastSuccessAt. Ein Rechner, der aus Restow entfernt wurde (seit 0.4.5, siehe Deinstallation und erneute Anmeldung), steht in keiner Liste und keiner Zählung. Der Grund revoke_suggested (lange kein Kontakt) wird nur in der Weboberfläche gezeigt; die API meldet ihn nicht, und ein solcher Rechner ist ohnehin silent oder backup_overdue.

Freigaben und belegte Bytes

Der Vertrag der Integrations-API 1.4.0 (seit 0.4.0) ist additiv: Nichts wurde entfernt oder umbenannt.

GET /api/v1/status hat neben endpoints und guests ein Objekt fileShares: total (Freigaben, die nicht stillgelegt sind), protected (in einem aktivierten Backup-Job), withoutJob, failedLastBackup, warnings (die neueste Sicherung endete mit Warnungen, die niemand bestätigt hat), lastSuccessAt und restorePoints. Eine Freigabe in einem Backup-Job zählt auch in readiness und recoveryReadiness.
Die Zusammenfassung der Wiederherstellbarkeit von GET /api/v1/verify/latest hat sharesWithoutJob: Freigaben in keinem Backup-Job, die einen Sicherungsstand behalten, danach bewertet werden, aber von nichts gesichert werden. Wie Rechner und Gäste ohne Job macht jede davon overall mindestens gelb.
events ist beim Anlegen eines Webhooks optional, siehe Webhooks.
physicalBytes von GET /api/v1/status und von usage in GET /api/v1/storage enthalten jetzt die restic-Repositories (seit 0.4.1): von Rechnern, Freigaben und Proxmox-VE-Containern, neben dem Chunk-Store. Die Felder und ihre Typen bleiben. Das Repository eines Containers zählt ab seiner nächsten Sicherung, das eines Rechners oder einer Freigabe wie bisher (ab der nächsten Sicherung oder dem nächsten Aufbewahrungslauf); bis dahin zählt es als null. Die Größe eines restic-Repositorys hat keinen Verlauf, das Wachstum des Belegten stammt daher nur aus dem Chunk-Store.

Vertrag 1.5.0 (seit 0.4.2)

Der Vertrag der Integrations-API 1.5.0 ist additiv: Nichts wurde entfernt oder umbenannt, und info.version von GET /api/v1/openapi.json sagt 1.5.0 (die Version des Vertrags; x-restow-build trägt den laufenden Build).

storageIntegrity.state kann unreadable sein. Das Objekt storageIntegrity im Bericht von GET /api/v1/verify/latest (neben lastCheckedAt und lastFullCheckAt) gibt das Ergebnis der letzten Speicherprüfung als state: ok, repaired, unreadable, corrupt oder never (bis eine lief). unreadable heißt, dass Pack-Dateien im Moment nicht gelesen werden konnten, wegen eines Übertragungs- oder Berechtigungsfehlers, was kein nachgewiesener Schaden ist; die nächste Speicherprüfung liest sie zuerst erneut. corrupt bedeutet weiterhin Packs mit nachgewiesenem Schaden. Ein Client, der die Werte vollständig abfragt, sollte unreadable akzeptieren und ihn als etwas behandeln, das man ansehen sollte, nicht als Schaden. Die Regeln dahinter stehen unter Beschädigt oder vorübergehend nicht lesbar.
Eine gestoppte Sicherung ist kein Fehler. Ein Lauf eines Servers oder Clients, den jemand in der Weboberfläche gestoppt hat, endet cancelled, ein neuer Lauf- und Aufgabenstatus für Rechner. Er löst keinen Webhook job.failed und keinen Fehleralarm aus und zählt nicht als letzte Sicherung (Endpoint-Backup).
Neue Routen der Weboberfläche gehören nicht zum Vertrag. Seit 0.4.2 nennen die Release-Notes Routen wie GET /api/v1/storage/destination, POST /api/v1/pve/guests/:id/repository/reset, POST /api/v1/pve/guests/:id/verify, POST /api/v1/pve/verify-unverified, GET und PUT /api/v1/settings/pve, GET /api/v1/snapshots/:id/calendar und GET /api/v1/snapshots/people. Sie sind es, die die Schaltflächen der Weboberfläche aufrufen. Sie brauchen eine angemeldete Sitzung, stehen nicht in der OpenAPI-Beschreibung, erreicht ein API-Schlüssel nicht, und sie können sich mit der Oberfläche ändern. Sie stehen unter API-Referenz.

Archiv-Erfassung (seit 0.4.4)

Der Vertrag 1.5.0 bleibt durch die Archiv-Erfassung seit 0.4.4 (Graph, IMAP-Archivierung und weitergeleitete Kopien, siehe Archivierung) unverändert: Es wurde kein Feld hinzugefügt, entfernt oder umbenannt, und info.version sagt weiterhin 1.5.0. Was eine Integration sieht:

GET /api/v1/archive/status und GET /api/v1/archive/report (Scope archive:read) zählen weitergeleitete Kopien in ihren Gesamtzahlen (items, intake, Anzahl und Größe der Elemente eines Berichts), führen sie aber noch nicht als eigenen Weg auf. Die Wege bleiben journal, graphSync, imapSync und fileImport; die Wege können sich also zu weniger als der Gesamtzahl summieren, wenn es weitergeleitete Kopien gibt. Ein Client sollte nicht annehmen, dass sie sich zur Gesamtzahl summieren. Der Vertrag nennt weitergeleitete Kopien noch nicht; ein eigener Weg ist geplant.
graphSync und imapSync tragen jetzt Zahlen. Sie waren von Anfang an Teil des Vertrags, aber nichts schrieb sie; seit 0.4.4 tun es die Graph-Erfassung und die IMAP-Archivierung (lastCapturedAt und last24h je Weg).
Der Kettenzustand steht in beiden Aufrufen weiterhin auf not_verified, und der Nachweisbericht ist weiterhin nur JSON.

Die Weboberfläche und ihre Session-API bekommen Felder und Routen, die nicht Teil des Vertrags sind: archiveCapture an Mail-Jobs, captureKind an ihren Mitgliedern und Kandidaten, mailSourceKinds in den Vorgaben eines neuen Jobs (GET /api/v1/backup-jobs/defaults?kind=mail), includeSuperseded an GET /api/v1/archive/search (die Erfassungen ausblendet, die ein stärkerer Weg ersetzt hat, es sei denn, es ist true) und die Routen des Erfassungsstatus, der Hold-Bestätigung und der Weiterleitungsadressen. Sie brauchen eine angemeldete Sitzung und können sich mit der Oberfläche ändern. Sie stehen in der API-Referenz unter Archiv-Erfassung (seit 0.4.4), und die Erfassungswege eines Jobs unter So gelangen E-Mails ins Archiv.

Vertrag 1.6.0 (seit 0.4.5)

Der Vertrag der Integrations-API 1.6.0 ist additiv: Nichts wurde entfernt oder umbenannt, und info.version von GET /api/v1/openapi.json sagt 1.6.0.

ObjectKind enthält group. Kalender und Unterhaltungen einer Microsoft-365-Gruppe (auch eines Teams) sind geschützte Objekte einer eigenen Art, group, mit eigenem letztem Snapshot (Quellen verbinden). Ein Client, der Objektarten vollständig abfragt, sollte den neuen Wert akzeptieren. Ein Gruppenpostfach zählt nie als geschütztes Postfach.
GET /api/v1/status meldet lastSuccess.groups neben mail, onedrive, imap, sharepoint und archive: die Abschlusszeit der neuesten wiederherstellbaren Sicherung eines Gruppenpostfachs ohne fehlgeschlagene Elemente. Es ist null, solange keine Gruppe gesichert wird, also nach dem Update, bis Gruppen eingeschaltet werden (sie sind Opt-in).
version.releasedAt im selben Aufruf: das Release-Datum des laufenden Builds, siehe Version und Updates.
Die Routen hinter den neuen Schaltflächen gehören nicht zum Vertrag. Einen ganzen Job stoppen und starten (POST /api/v1/backup-jobs/:id/cancel, POST /api/v1/pve/jobs/:id/run, POST /api/v1/pve/jobs/:id/cancel) und einen Rechner entfernen (POST /api/v1/endpoints/:id/remove, GET /api/v1/endpoints/removals) ruft die Weboberfläche auf. Sie brauchen eine angemeldete Sitzung, stehen nicht in der OpenAPI-Beschreibung und sind mit einem API-Schlüssel nicht erreichbar. Sie stehen unter API-Referenz.
Eine gestoppte Sicherung ist weiterhin kein Fehler. Eine Sicherung eines Rechners, einer Dateifreigabe oder eines Proxmox-VE-Gasts, die jemand stoppt, endet cancelled, wie es eine einzeln gestoppte Sicherung seit 0.4.2 tut (Vertrag 1.5.0); seit 0.4.5 gilt dasselbe, wenn ein ganzer Job gestoppt wird.

Vertrag 1.7.0 (seit 0.4.7)

Der Vertrag der Integrations-API 1.7.0 ist additiv, und info.version von GET /api/v1/openapi.json sagt 1.7.0, mit einer Änderung der Bedeutung, die einen Client brechen kann: der Status orphaned.

status: "orphaned" heißt nicht mehr „an der Quelle gelöscht“

Vor 0.4.7 war ein Objekt mit dem Status orphaned aus seiner Quelle entfernt. Seit 0.4.7 ist es jedes Objekt, das nicht mehr gesichert wird: auch eines, das noch an der Quelle steht, dessen Konto aber deaktiviert ist, das keine Exchange-Online-Lizenz hat oder das Microsoft gesperrt hat (ein OneDrive oder eine SharePoint-Website, HTTP 423). Seine Sicherungen bleiben erhalten, und die Sicherung setzt von selbst wieder ein, wenn das Konto wieder aktiviert, lizenziert oder entsperrt ist. Das neue Feld statusReason unterscheidet sie: account_disabled, no_license oder locked, und null bei einem aus der Quelle entfernten Objekt. Es gilt in GET /api/v1/objects, im object von GET /api/v1/jobs (neben object.status) und in den Objekten von GET /api/v1/users; objects.orphaned von GET /api/v1/status zählt alle. Eine Integration, die orphaned als gelöschtes Konto behandelt, zum Beispiel um einen Nutzer in einem PSA zu schließen, muss statusReason prüfen, bevor sie handelt.

Alles andere ist additiv:

GET /api/v1/users. Die Objekte eines Nutzers tragen zusätzlich inactiveSince (seit wann das Objekt nicht mehr gesichert wird) und statusConfirmedAt (wann eine Administration bestätigt hat, dass das beabsichtigt ist; null, solange es noch wartet). Die recoveryReadiness eines Nutzers steht mindestens auf Gelb, nie auf Grün, solange eines seiner Objekte auf diese Bestätigung wartet, und auf Gelb statt null, wenn ein solches Objekt keine Sicherung zu bewerten hat.
toConfirm. Die Zusammenfassung der Wiederherstellbarkeit von GET /api/v1/status und GET /api/v1/verify/latest zählt die Objekte, die nicht mehr gesichert werden und auf eine Bestätigung warten. Jedes davon setzt overall mindestens auf Gelb, nie auf Rot.
guests.excluded. GET /api/v1/status lässt die Proxmox-VE-Gäste, die eine Administration von der Sicherung ausgeschlossen hat, aus guests.total und guests.withoutJob heraus und meldet ihre Zahl als guests.excluded (Einen Gast von der Sicherung ausschließen).
Ein neuer Überspringgrund. POST /api/v1/jobs/backup überspringt ein Objekt mit dem Grund inactive, wenn es nicht mehr gesichert wird und noch an der Quelle steht (statusReason gesetzt); ein aus der Quelle entferntes Objekt wird weiterhin als orphaned übersprungen. Die übrigen Gründe sind excluded, source_pending, source_disabled und already_queued. Ein Client, der die Gründe vollständig abfragt, sollte inactive akzeptieren.
Webhooks. job.completed und job.failed einer abgeschlossenen Wiederherstellung tragen ihre Zähler in data.job.result (restored, skipped, failures, unverified). report.alert kann vier neue Ereignisse nennen: object.inactive, object.inactive_many, source.app_secret_expiring und installation.app_secret_expiring (Benachrichtigungen und Berichte). Ein Client, der Ereignisnamen vollständig abfragt, sollte sie akzeptieren.
Einige Werte folgen neuen Regeln. Eine Sicherung, die Microsoft Graph oder der Speicher gebremst hat, und eine Sicherung, die neutral endete, weil ein Objekt nicht mehr gesichert wird, lösen kein job.failed aus (Sicherungen, die ein Dienst gebremst hat). objects.failed von GET /api/v1/status lässt Objekte aus, deren letzte Sicherung ein Dienst gebremst hat oder neutral endete, weil ein Objekt nicht mehr gesichert wird; stattdessen zählt der Lauf davor. Ein aus seiner Quelle entferntes Objekt wird ohne das Alter seiner letzten Sicherung bewertet (report.reasons von GET /api/v1/verify/latest lässt das Alter aus) und ist nie überfällig, in GET /api/v1/status, /objects, /users und /verify/latest wie in der Benachrichtigung verify.completed. GET /api/v1/jobs behält für eine gebremste oder neutrale Sicherung den Status failed: Lesen Sie failure.code (graph.throttled, graph.service_unavailable, storage.rate_limited für gebremst; graph.mailbox_inactive, graph.object_locked, config.object_inactive für neutral) und das statusReason des Objekts und behandeln Sie sie wie den Zustand des Objekts, nicht wie einen Fehler. Der Vertrag hat noch kein Feld, das sie von einem Fehler unterscheidet.
Die Routen hinter den neuen Schaltflächen gehören nicht zum Vertrag. Ein Objekt bestätigen (POST /api/v1/directory/objects/:id/inactive/confirm, POST /api/v1/directory/objects/inactive/confirm), das Ablaufdatum der eigenen App einer Quelle (PATCH /api/v1/sources/:id/own-app/expiry), einen Gast ausschließen (PUT /api/v1/pve/guests/:id/excluded) und die Preise (GET und PUT /api/v1/settings/pricing) ruft die Weboberfläche auf. Sie brauchen eine angemeldete Sitzung, stehen nicht in der OpenAPI-Beschreibung und sind mit einem API-Schlüssel nicht erreichbar. Sie stehen unter API-Referenz.

Version und Updates

GET /api/v1/status meldet die laufende Version und den Opt-in-Update-Hinweis in einem Objekt version, damit ein RMM veraltete Installationen markieren kann. Seine Felder: running, commit (der Quell-Commit des laufenden Builds, sofern bekannt), latest (das neueste Release des Kanals, wenn die Prüfung lief), updateAvailable (null, wenn das nicht bekannt ist), releaseUrl, updateCheck (disabled, pending, ok oder failed), checkedAt, channel (stable oder beta), latestTag (wie veröffentlicht, zum Beispiel v1.2.3), publishedAt, checkError (warum die letzte Prüfung scheiterte, zum Beispiel rate_limited oder not_found; null, wenn sie nicht scheiterte), maintenance (ein über den Updater angekündigtes oder laufendes Update, mit phase, targetVersion und startsAt; sonst null) und, seit 0.4.5, releasedAt (wann der laufende Build erschienen ist, das Commit-Datum seines Release-Tags als ISO-8601-UTC-Zeit; null für einen Build ohne eines). Die Update-Prüfung ist aus, bis eine Administration sie einschaltet; auf einer frischen Installation ist updateCheck daher disabled. Ein Status-Aufruf wartet nie auf das Netzwerk. Siehe Updates.

Warum ein Job fehlgeschlagen ist

Job-Objekte tragen neben der einfachen errorMessage die Ursache eines Fehlers. failure enthält einen stabilen Ursachen-code (zum Beispiel graph.consent_missing, graph.throttled, imap.auth_failed, storage.full, verify.hash_mismatch oder unknown), seine category, ob Warten allein helfen kann (transient) oder ein manueller Neuversuch sinnvoll ist (retryable), params (die fehlende Berechtigung, den Host, die Wartezeit in Sekunden), geschwärzte technical-Details für einen Supportfall, occurredAt, den step, in dem der Lauf war, den automatischen retry-Zustand, die geordneten steps zur Behebung und eine docsUrl. Bei einem Job, der nicht fehlgeschlagen ist oder keine erfasste Ursache hat, ist er null. Seit 0.4.7 kann ein Job mit dem Status failed eine Ursache tragen, die kein Fehler der Sicherung ist: vom Dienst gebremst (graph.throttled, graph.service_unavailable, storage.rate_limited) oder neutral, weil ein Objekt nicht mehr gesichert wird (graph.mailbox_inactive, graph.object_locked, config.object_inactive); siehe Vertrag 1.7.0. itemCauses nennt die Ursachen hinter den fehlgeschlagenen Elementen eines beendeten Jobs, die häufigste zuerst (höchstens drei). Das Job-Detail ergänzt jedes fehlgeschlagene Element um ein failure und liefert failureGroups, die fehlgeschlagenen Elemente nach Ursache gruppiert. Siehe Fehlererklärungen.

Webhooks

Restow ruft eine von Ihnen registrierte URL auf, wenn ein gewähltes Ereignis eintritt, zum Beispiel, damit ein PSA ein Ticket eröffnet, wenn eine Sicherung fehlschlägt. Derzeit definierte Ereignisse: job.failed, job.completed, verify.completed, dazu ein manuelles „Testereignis senden“; die signierten report.alert und report.summary kommen aus Alarm- und Berichts-Regeln. Jeder Webhook hat sein eigenes Signatur-Secret, einmal bei der Erstellung angezeigt (oder nach Secret erneuern): Jede Zustellung ist ein signierter JSON-POST, signiert als sha256=<HMAC-SHA-256 des rohen Bodys> im Header X-Restow-Signature, zusammen mit X-Restow-Event, X-Restow-Delivery und X-Restow-Attempt. Prüfen Sie die Signatur (zeitkonstanter Vergleich), bevor Sie einer Anfrage vertrauen. Eine Antwort ohne 2xx-Status wird nach 1 Min., 5 Min., 15 Min., 1 Std., 3 Std., 6 Std. und 12 Std. erneut versucht; HTTP 410 beendet die Zustellung sofort. Das Zustellprotokoll behält jeden Versuch etwa 30 Tage nach Abschluss, und eine Zustellung lässt sich auf Anfrage erneut senden. Seit 0.3.1 (Integrations-API-Vertrag 1.3.0) hat ein Webhook außerdem ein format: restow ist das hier beschriebene signierte JSON und der Standard, discord, slack und teams senden eine Chatnachricht ohne Signatur. Siehe Benachrichtigungen und Berichte.

Welche Ereignisse ein Webhook erhält, bestimmt seine Spalte in der Benachrichtigungsmatrix (seit 0.4.0, Integrationen → Benachrichtigungen). events beim Anlegen oder Ändern eines Webhooks bedeutet weiterhin die abonnierten Strom-Ereignisse (job.failed, job.completed, verify.completed), und seit Vertrag 1.4.0 ist es beim Anlegen optional: Ein Webhook, der ohne es angelegt wird, beginnt mit den Voreinstellungen seines Formats (ein Discord-, Slack- oder Teams-Webhook erhält Fehler und Warnungen, ein signierter restow-Webhook alles). Die Namen und Nutzdaten des Stroms sind unverändert; backup.succeeded ist der Name der Matrix für das, was der Strom job.completed nennt, ein Alias und keine Umbenennung. Die Sitzungs-API (die der Weboberfläche) liefert die Spalte eines Webhooks außerdem als notifyEvents. Siehe die Matrix und der Strom.

Die Nutzlast von job.failed (data.job) trägt die Ursache als failure: den stabilen code, ob Warten allein helfen kann (transient) und die params, die ein Ticket braucht. Auch ein fehlgeschlagener Lauf eines Servers oder Clients löst job.failed aus, mit queue gleich endpoint_backup oder endpoint_restore und einem zusätzlichen data.endpoint (id, hostname, displayName, profile, os). Ein Lauf, den der Agent wegen eines Neustarts unterbrechen musste, ist kein Fehlschlag und löst keinen Webhook aus. Das tut auch eine Mail-&-SaaS-Sicherung nicht, die Microsoft Graph oder der Speicher gebremst hat, oder eine, die neutral endete, weil ein Objekt nicht mehr gesichert wird (seit 0.4.7). Eine Wiederherstellung, die abgeschlossen wurde, ohne etwas wiederherzustellen, während Elemente fehlschlugen, löst job.failed aus, mit data.job.status weiterhin completed, und ein Job, den der Reconciler endgültig beendet, löst es ebenfalls aus. Läufe von Freigaben lösen job.completed und job.failed aus, mit queue auf file-share-backup, file-share-restore oder file-share-copy, protectedObjectId null und zusätzlich data.fileShare (id, name, protocol) (seit 0.4.0).

Webhook-Ziele in Loopback- oder privaten Netzen werden abgelehnt, sofern der Betreiber sie nicht erlaubt hat (RESTOW_WEBHOOK_ALLOW_PRIVATE); Link-Local (Cloud-Metadaten) und andere reservierte Bereiche werden unabhängig von dieser Einstellung immer abgelehnt.

Auditierung

Jeder Lesezugriff auf Nutzer- oder Sicherungsdaten über die API (durch einen Schlüssel oder durch die Web-Oberfläche) wird genauso ins Audit-Log geschrieben: wer (bzw. welcher Schlüssel), wann, was, für wen und von welcher IP.