Webhooks

Einleitung

Webhooks ermöglichen die Benachrichtigung eines vordefinierten Empfängers über Ereignisse im Arbeitsbereich mithilfe von HTTP/HTTPS-Callbacks. Benutzer können Webhooks so konfigurieren, dass Ereignisse im Arbeitsbereich Aktionen in externen Diensten auslösen. Dieser Ansatz eignet sich zur Synchronisierung und Nachverfolgung bestimmter Ereignisse.

Verwenden Sie Webhooks, um auf der Seite jeder von Ihnen verwendeten Anwendung oder Website benutzerdefinierte Aktionen basierend auf verschiedenen Ereignissen in ONLYOFFICE Apps durchzuführen.

Sie können alle Ihre Webhooks erstellen und verwalten, sie konfigurieren und den Verlauf jedes Webhooks durchsuchen, um deren Leistung zu überprüfen.

Einen neuen Webhook erstellen

Zunächst müssen Sie in Ihrem externen Dienst einen Endpunkt für Webhooks einrichten. Dieser Endpunkt dient dazu, Webhooks des Arbeitsbereichs zu empfangen und Ereignisbenachrichtigungen abzufangen.

Sobald Sie Ihren Endpunkt erstellt und konfiguriert haben, können Sie Webhooks im Arbeitsbereich erstellen. So erstellen Sie einen neuen Webhook:

1. Öffnen Sie den Abschnitt Entwicklertools, indem Sie auf den Link Entwicklertools klicken, der in jedem Abschnitt (Dateien, Räume, Formulare) im linken Bereich verfügbar ist.

   hinweis

   Standardmäßig ist der Zugriff auf den Bereich Entwicklertools für alle Benutzer außer Gästen aktiviert, sodass jeder Benutzer auf diese Seite zugreifen und entsprechend eigene Webhooks erstellen kann. Administratoren können alle erstellten Webhooks einsehen, Benutzer hingegen nur ihre eigenen.

   Administratoren können sowohl den Link Entwicklertools auf der linken Seite verwenden als auch über das Menü in der unteren linken Ecke der Einstellungen des Arbeitsbereichs zu diesem Abschnitt wechseln, indem sie die Option Einstellungen -> Entwicklertools auswählen.

2. Gehen Sie in den Entwicklertools zum Abschnitt Webhooks.

3. Klicken Sie auf die Schaltfläche Webhook erstellen.

4. Legen Sie die erforderlichen Parameter fest:

   

   • Webhook name – ein Identifikationsname zur bequemen Arbeit mit dem Webhook im Arbeitsbereich.

   • Payload URL – eine Adresse des Endpunkts, an den der Webhook gesendet werden soll.

   • Secret key (Geheimer Schlüssel) – Legen Sie einen Webhook-Schlüssel fest, mit dem Sie Anfragen an die Payload-URL verifizieren können. Geben Sie Ihren eigenen Schlüssel ein oder klicken Sie auf Generieren. Bitte beachten Sie: Ihr geheimer Schlüssel kann nach dem Speichern nicht wiederhergestellt werden. Falls Sie diesen Schlüssel verloren oder vergessen haben, öffnen Sie die Webhook-Einstellungen und klicken Sie auf den Link Schlüssel zurücksetzen, um einen neuen zu generieren. Alle Integrationen, die den vorherigen Schlüssel verwenden, müssen aktualisiert werden.

     

   • SSL verification (SSL-Verifizierung) – Diese Option ist standardmäßig aktiviert, um SSL-Zertifikate bei der Übertragung von Nutzdaten zu überprüfen. Es wird nicht empfohlen, diesen Parameter zu deaktivieren.

   • Event to trigger this webhook - Verwenden Sie die Option Alles senden oder aktivieren Sie das Optionsfeld Einzelne Ereignisse und wählen Sie nur die gewünschten Auslöser aus, z. B. Ereignisse bei Änderungen an Elementen des Arbeitsbereichs wie Benutzern, Gruppen, Dateien, Ordnern, Räumen, Formularen und KI-Agenten. Beispiele hierfür sind: Benutzer erstellt, eingeladen, aktualisiert, gelöscht usw.

   • Target ID (Ziel-ID) - Eine Kennung für einen Benutzer, eine Gruppe, eine Datei oder einen Ordner, mit der Sie Änderungen an einem Objekt nachverfolgen können.

   

5. Die Payload-URL muss auf eine HTTP-Anfrage mit der HEAD-Methode mit dem Status 200 antworten.

6. Klicken Sie auf die Schaltfläche Erstellen.

Je nach Einstellungen wird der erstellte Webhook entweder allen Ereignissen des Arbeitsbereichs oder nur dem/den ausgewählten Auslöser(n) zugewiesen. Sie erhalten automatische Benachrichtigungen zu Ereignissen des Arbeitsbereichs in Ihrem externen Dienst. Auslöser, die bei der Erstellung für einen bestimmten Webhook ausgewählt wurden, werden nur dann ausgelöst, wenn der Webhook-Inhaber Zugriffsrechte auf die geänderte Entität des Arbeitsbereichs besitzt.

Webhooks verwalten

Die erstellten Webhooks werden mit Name, Autor, Payload-URL und Status aufgelistet. Sie können einen Webhook mithilfe des Schalters in der Spalte Status deaktivieren oder wieder aktivieren. Verwenden Sie das Symbol auf der rechten Seite, um das Kontextmenü mit den folgenden Optionen zu öffnen:

• Einstellungen - ändern Sie die bei der Erstellung des Webhooks festgelegten Einstellungen.
• Webhook-Verlauf - zeigen Sie den Zustellungsverlauf des Webhooks an.
• Webhook löschen - löschen Sie den Webhook.

Klicken Sie auf den Webhook, um den Webhook-Verlauf anzuzeigen

Beim Anzeigen des Verlaufs können Sie Webhooks nach Zustellungsdatum oder Status (Nicht gesendet, 2XX, 3XX, 4XX, 5XX) filtern. Klicken Sie auf die Filterschaltfläche , wählen Sie die gewünschten Parameter aus und klicken Sie auf Anwenden.

Sie können einen oder mehrere Webhooks in der Liste auswählen und die Option Wiederholen verwenden, die oben angezeigt wird, um die ausgewählten Webhooks erneut zuzustellen. Oder klicken Sie auf das Symbol neben dem entsprechenden Webhook und wählen Sie im Kontextmenü die Option Wiederholen aus.

Klicken Sie auf das Symbol neben dem entsprechenden Webhook und wählen Sie im Kontextmenü die Option Webhook-Details aus.

Folgende Details sind verfügbar:

• Status – ein Antwortstatus.
• Event ID – eine ID des Ereignisses.
• Event type – das Ereignis, das zur Aktivierung des Webhooks geführt hat.
• Event time – ein Datum, an dem das Ereignis stattfand.
• Delivery time – ein Datum, an dem die Antwort vom Endpunkt empfangen wurde.

In den Abschnitten Anfrage/Antwort können Sie außerdem den POST-Anfrageheader, den POST-Anfragetext, den POST-Antwortheader und den POST-Antworttext anzeigen. Verwenden Sie das Symbol , um den Anfrage- oder Antwortheader bzw. -text in die Zwischenablage zu kopieren.

Verwenden Sie das Symbol neben der Beschriftung Webhook-Details, um den Webhook erneut zuzustellen.

Technische Details

Für die Arbeit werden folgende zwei Dienste genutzt:

1. ASC.Web.Studio stellt Methoden zum Senden von Webhooks bereit und startet WorkerService.

   WorkerService – abonniert den Empfang von Nachrichten von einem Broker (beispielsweise wird standardmäßig RabbitMQ verwendet), der Informationen über neue Webhooks speichert, die darauf warten, gesendet zu werden. Die vom Broker empfangenen Nachrichten werden in eine Warteschlange gestellt. Diese Warteschlange wird anschließend kontinuierlich abgefragt und kontaktiert asynchron den ASC.Webhooks.Service, um Webhooks zu senden.

2. ASC.Webhooks.Core bietet Methoden zum Veröffentlichen von Webhooks in der Datenbank und im Message Broker sowie Methoden zur Arbeit mit der Datenbank.

Weitere Details zur ONLYOFFICE Apps API finden Sie unter api.onlyoffice.com.