Webhooks

Einleitung

Webhooks ermöglichen die Benachrichtigung eines vordefinierten Empfängers über Ereignisse im Portal mithilfe von HTTP/HTTPS-Callbacks. Benutzer können Webhooks so konfigurieren, dass Ereignisse im Portal 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 DocSpace 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, DocSpace-Webhooks zu empfangen und Ereignisbenachrichtigungen abzufangen.

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

1. Öffnen Sie den Abschnitt Entwicklertools, indem Sie auf den Link Entwicklertools klicken, der in jedem Abschnitt (Räume, Dokumente) im linken Bereich verfügbar ist.
   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 DocSpace-Einstellungen 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 Portal.
   • 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, können Sie ihn zurücksetzen. In diesem Fall müssen jedoch alle Integrationen, die diesen Schlüssel verwenden, 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.
   • Trigger - 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 Portalelementen wie Benutzern, Gruppen, Dokumenten, Ordnern und Räumen. 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 DocSpace-Ereignissen oder nur dem/den ausgewählten Auslöser(n) zugewiesen. Sie erhalten automatische Benachrichtigungen zu DocSpace-Ereignissen 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 DocSpace-Entität besitzt.

Webhooks verwalten

Sie können den erstellten Webhook mithilfe des daneben stehenden Schalters deaktivieren oder wieder aktivieren. Verwenden Sie das Symbol auf der rechten Seite, um die bei der Erstellung des Webhooks festgelegten Einstellungen zu ändern, den Verlauf des Webhooks anzuzeigen oder den Webhook zu löschen.

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.
• Trigger – der Auslöser, der 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 DocSpace API finden Sie unter api.onlyoffice.com.