Webhook-Einstellungen

Ein Webhook ist eine dedizierte Empfangsadresse, über die andere Programme Dateien automatisch in einen festgelegten Ordner von SpaceBuilder übertragen. So lassen sich zum Beispiel Dateien, die ein Scanner, ein Geschäftssystem oder ein Automatisierungsprogramm erzeugt, ohne manuelles Eingreifen in einem Ordner speichern.

Auf dieser Seite legt der Administrator den serverweiten Nutzungsumfang und die Limits für Webhooks fest. Wie Sie in einem Ordner tatsächlich einen Webhook anlegen und die Empfangsadresse verwenden, lesen Sie unter Ordner-Webhooks verwenden.

Vor der Einrichtung prüfen

Damit Webhooks von außen aufgerufen werden können, muss eine Adresse vorhanden sein, über die SpaceBuilder erreichbar ist.
Die Webhook-Adresse enthält ein Geheimnis zur Authentifizierung. Die vollständige Adresse teilen Sie nur mit dem Administrator und der für das anbindende Programm zuständigen Person.
Bei einer Veröffentlichung im Internet wird HTTPS empfohlen.
Je größer die empfangenen Dateien, desto höher der Arbeitsspeicher- und Speicherplatzverbrauch des Servers.

Webhook-Richtlinie festlegen

Webhook-Nutzungseinstellungen

In den Administratoreinstellungen wählen Sie, wer die Webhook-Funktion nutzen darf und mit welcher Sicherheitsstufe.

Feld	Beschreibung
Eingehende Webhooks aktivieren	Schaltet die Webhook-Empfangsfunktion des Servers ein. Ist sie ausgeschaltet, werden auch über bereits angelegte Webhook-Adressen keine Dateien empfangen.
Ausgabe von Benutzer-API-Schlüsseln zulassen	Erlaubt es, in Ordnern Webhook-Empfangsadressen zu erstellen und zu verwalten. Ist die Option ausgeschaltet, kann niemand, auch kein Administrator, in einem Ordner einen neuen Webhook anlegen.
Webhooks in persönlichen Ordnern erlauben	Erlaubt Webhooks nicht nur in Teamordnern, sondern auch in den persönlichen Ordnern der Benutzer. Schalten Sie die Option ein, wenn Dateien in persönlichen Ordnern empfangen werden sollen.
Speichern in Unterordnern erlauben	Erlaubt es Benutzern, für jeden Webhook `Unterordner` einzuschalten. Ein so eingestellter Webhook speichert Dateien entlang des im Dateinamen angegebenen Unterpfads und legt fehlende Ordner an. Standardmäßig ist die Option ausgeschaltet; solange sie ausgeschaltet ist, nehmen auch bereits auf `Erlaubt` gesetzte Webhooks keine Dateien mit Unterpfad an.
Webhook-Signaturprüfung erzwingen (Sicherheit)	Wendet auf neu erstellte Webhooks und auf Webhooks mit ausgetauschtem Geheimnis eine zusätzliche Signaturprüfung an. Diese Sicherheitsfunktion wird verwendet, wenn das aufrufende Programm HMAC-Signaturen unterstützt; standardmäßig ist sie ausgeschaltet.

Kapazität und Anfragelimits festlegen

Legen Sie fest, welche Größe und wie viele Anfragen ein Webhook auf einmal empfangen kann. In üblichen Umgebungen können Sie die Standardwerte beibehalten.

Feld	Standardwert	Beschreibung
Maximale Payload-Größe	8 MB	Die Gesamtgröße aus Datei und Anfragedaten, die ein Webhook auf einmal empfangen kann. Dies ist der Standardwert des Servers; er kann erhöht werden, wenn größere Dateien empfangen werden müssen.
Globales Ratenlimit	5 pro Sekunde	Verhindert, dass in kurzer Zeit zu viele Anfragen eintreffen. Passen Sie den Wert nur an, wenn reguläre Anfragen begrenzt werden.

Die Payload bezeichnet den gesamten über den Webhook übertragenen Inhalt, also Datei und Anfragedaten zusammen. Da sie auch Informationen außer der Datei enthält, kann die angezeigte Größe etwas größer sein als die eigentliche Datei.

Wird die festgelegte Größe überschritten, wird die Datei nicht gespeichert und die Antwort 413 Request Entity Too Large zurückgegeben. Für Umgebungen, in denen häufig große Dateien übertragen werden, ist der normale Datei-Upload besser geeignet.

Auf einmal empfangbare Größe erhöhen

Wenn Sie über einen Webhook Dateien empfangen müssen, die größer als 8 MB sind, ändern Sie die Einstellung wie folgt.

Öffnen Sie auf der Administrationsseite Servicekonfiguration > Dateibereich und klappen Sie die Karte Webhook (automatischer Datenempfang) auf.
Geben Sie im Feld Maximale Payload-Größe die benötigte Größe ein.
Wählen Sie rechts neben dem Eingabefeld die Einheit MB oder GB.
Speichern Sie die Einstellungen.
Prüfen Sie die Übertragung zuerst mit einer kleinen Datei, bevor Sie die eigentlichen Dateien senden.

Um beispielsweise Dateien bis etwa 20 MB zu empfangen, geben Sie als Zahl 20 ein und wählen die Einheit MB. Der vom Server unterstützte Einstellungsbereich ist 1 KB~1 GB.

Wenn Sie den Webhook im Internet veröffentlichen, können Sie auch in Cloudflare oder Nginx Anfragelimits festlegen, um ungewöhnlich viele Anfragen abzufangen, bevor sie den Server erreichen.

Empfohlene Reihenfolge der Einrichtung

Schalten Sie Eingehende Webhooks aktivieren ein.
Schalten Sie Ausgabe von Benutzer-API-Schlüsseln zulassen ein, damit in Ordnern Webhooks erstellt werden können.
Schalten Sie Webhooks in persönlichen Ordnern erlauben nur ein, wenn Dateien in persönlichen Ordnern empfangen werden müssen.
Behalten Sie für Kapazität und Anfragelimits die Standardwerte bei.
Speichern Sie die Einstellungen und erstellen Sie anschließend im tatsächlich genutzten Ordner einen Webhook.
Senden Sie zuerst eine kleine Testdatei, um Speicherort und Berechtigungen zu prüfen.

Bei Problemen

Symptom	Zu prüfen
Dateien werden nicht empfangen	Prüfen Sie, ob die Inbound-Webhook-Funktion und die Schlüsselausgabe für Benutzer eingeschaltet sind.
Antwort `401`	Prüfen Sie, ob das Geheimnis der Webhook-Adresse oder die Signatur-Header korrekt sind.
Antwort `403`	Prüfen Sie, ob persönliche Ordner erlaubt sind und ob die Berechtigungen des Zielordners stimmen.
Antwort `409`	Prüfen Sie, ob der Webhook pausiert ist oder mit der Richtlinie für gleichnamige Dateien kollidiert.
Antwort `413`	Prüfen Sie, ob die Gesamtgröße der Anfrage die maximale Payload-Größe überschreitet.
Server wird nach dem Empfang langsam	Verringern Sie Payload-Größe und Anfragehäufigkeit und prüfen Sie, ob sich OCR- und Dokumentkonvertierungsaufgaben stauen.