Standard-Webhooks in Enquete einrichten und verwalten

Mit Standard-Webhooks kann Enquete automatisch umfragebezogene Informationen an eine andere Anwendung senden, sobald ein ausgewähltes Ereignis eintritt.

Wenn ein Teilnehmer beispielsweise eine Umfrage absendet oder abschließt, kann Enquete die Ereignisdaten direkt an Ihr Customer-Relationship-Management-System, Ihre Berichtsplattform, Ihre interne Datenbank, Ihre Supportanwendung, Ihre Marketingplattform oder einen anderen externen Dienst senden.

Dadurch kann Ihre Organisation Arbeitsabläufe automatisieren und Umfragedaten zwischen Systemen übertragen, ohne Antworten wiederholt exportieren oder Informationen manuell übertragen zu müssen.

In dieser Anleitung wird erläutert, wie Sie Standard-Webhooks über die Enquete-Benutzeroberfläche erstellen, konfigurieren, testen, überwachen und verwalten.

 

 

Was ist ein Standard-Webhook?

Ein Standard-Webhook ist eine automatisierte Verbindung zwischen Enquete und einer externen Anwendung.

Wenn in einer ausgewählten Umfrage ein Ereignis eintritt, sendet Enquete eine HTTP-POST-Anfrage an die Endpunkt-URL, die im Webhook-Abonnement konfiguriert wurde.

Abhängig vom Arbeitsablauf Ihrer Organisation kann ein Webhook für folgende Zwecke verwendet werden:

• Neue Umfrageantworten an ein CRM-System senden.
• Umfragedaten in einer internen Datenbank speichern.
• Ein Support- oder Customer-Success-Team benachrichtigen.
• Einen Berichts- oder Analyseprozess starten.
• Einen Datensatz in einer anderen Anwendung erstellen oder aktualisieren.
• Einen benutzerdefinierten internen Geschäftsprozess auslösen.

Jeder Standard-Webhook ist mit einer bestimmten Umfrage und einem bestimmten Ereignistyp verbunden. Dadurch können Sie steuern, welche Aktivitäten eine Übertragung auslösen und wohin die Informationen gesendet werden.

 

Bevor Sie einen Webhook erstellen

Bevor Sie einen Standard-Webhook einrichten, stellen Sie sicher, dass Ihr technisches Team Folgendes vorbereitet hat:

• Einen öffentlich zugänglichen HTTPS-Endpunkt.
• Einen Server, der HTTP-POST-Anfragen empfangen kann.
• Einen Prozess zum Lesen von JSON-Anfragekörpern.
• Einen sicheren Speicherort für das Webhook-Geheimnis.
• Einen Prozess zur Überprüfung von Webhook-Signaturen.
• Eine Methode zur Vermeidung doppelter Ereignisverarbeitung.

Der empfangende Endpunkt sollte schnell reagieren, nachdem er eine Anfrage angenommen hat. Lang laufende Vorgänge sollten normalerweise an eine Warteschlange oder ein Hintergrundverarbeitungssystem übergeben werden, nachdem der Endpunkt eine erfolgreiche Antwort zurückgegeben hat.

Entwickler sollten vor der Implementierung des empfangenden Endpunkts die offizielle Webhook-Dokumentation lesen.

 

Standard-Webhooks öffnen

Schritt 1: Integrationen öffnen

Wählen Sie in Ihrem Enquete-Dashboard oben im Menü Integrationen aus.

 

Schritt 2: Standard-Webhooks auswählen

Öffnen Sie Standard-Webhooks aus den verfügbaren Integrationsoptionen.

Die Übersicht der Standard-Webhooks zeigt alle Webhook-Abonnements an, die in Ihrem Konto verfügbar sind.

Auf dieser Seite können Sie:

• Einen neuen Webhook erstellen.
• Vorhandene Webhook-Abonnements anzeigen.
• Webhook-Einstellungen bearbeiten.
• Webhook-Geheimnisse anzeigen und kopieren.
• Testübertragungen senden.
• Übertragungsprotokolle überprüfen.
• Einen Webhook aktivieren oder deaktivieren.
• Einen Webhook löschen.

 

Einen Standard-Webhook erstellen

Schritt 1: Auf Webhook hinzufügen klicken

Klicken Sie in der Übersicht der Standard-Webhooks auf Webhook hinzufügen.

Ein Konfigurationsformular wird geöffnet.

Schritt 2: Endpunkt-URL eingeben

Geben Sie den HTTPS-Endpunkt ein, an den Enquete die Webhook-Übertragungen senden soll.

Zum Beispiel:

https://example.com/api/enquete/webhook

Der Endpunkt muss öffentlich zugänglich sein und HTTP-POST-Anfragen akzeptieren können.

Localhost-Adressen, private Entwicklungs-URLs und Seiten, die eine interaktive Anmeldung erfordern, können keine Webhook-Übertragungen von Enquete empfangen.

Schritt 3: Beschreibung hinzufügen

Geben Sie eine Beschreibung ein, die den Zweck des Webhooks eindeutig erklärt.

Zum Beispiel:

Abgeschlossene Kundenzufriedenheitsantworten an unser CRM-System senden

Eine klare Beschreibung erleichtert es, den Webhook später zu identifizieren, insbesondere wenn Ihre Organisation mehrere Abonnements verwaltet.

Schritt 4: Umfrage auswählen

Wählen Sie die Umfrage aus, deren Ereignisse den Webhook auslösen sollen.

Ein Standard-Webhook-Abonnement ist mit einer einzelnen Umfrage verbunden. Wenn Sie Ereignisse aus mehreren Umfragen senden möchten, erstellen Sie für jede Umfrage ein separates Webhook-Abonnement.

Schritt 5: Ereignistyp auswählen

Wählen Sie das Ereignis aus, das die Webhook-Übertragung auslösen soll.

Zu den Ereignissen, die in der Standard-Webhook-Benutzeroberfläche verfügbar sein können, gehören:

• survey.new.response
• survey.response.completed

Die verfügbaren Ereignisse können von der aktuellen Enquete-Konfiguration und den für Ihr Konto aktivierten Funktionen abhängen.

Schritt 6: Aktivierungsstatus auswählen

Wählen Sie aus, ob der Webhook sofort aktiv sein soll.

Wenn ein Webhook aktiv ist, sendet Enquete Übertragungen, sobald das ausgewählte Ereignis eintritt.

Wenn er inaktiv ist, bleibt die Konfiguration verfügbar, aber Übertragungen von Live-Ereignissen werden pausiert.

Sie können einen Webhook inaktiv lassen, während Ihr technisches Team den empfangenden Endpunkt vorbereitet oder testet.

Schritt 7: Webhook speichern

Klicken Sie auf Speichern, um das Webhook-Abonnement zu erstellen.

Der neue Webhook wird in der Übersicht der Standard-Webhooks angezeigt und kann sofort getestet werden.

 

Webhook-Geheimnis verwalten

Jeder Standard-Webhook verfügt über ein Geheimnis. Die empfangende Anwendung verwendet dieses Geheimnis, um zu überprüfen, ob eine eingehende Anfrage tatsächlich von Enquete stammt.

Das Webhook-Geheimnis sollte wie ein Passwort oder ein privater API-Zugangsschlüssel behandelt werden.

 

Schritt 1: Geheimnis anzeigen

Suchen Sie den Webhook in der Übersicht und klicken Sie auf das Augensymbol.

Das Geheimnis wird vorübergehend angezeigt.

Schritt 2: Geheimnis kopieren

Klicken Sie auf das Zwischenablagesymbol, um das Geheimnis zu kopieren.

Aus Sicherheitsgründen wird das Geheimnis nach ungefähr zehn Sekunden automatisch wieder ausgeblendet.

Schritt 3: Geheimnis sicher speichern

Geben Sie das Geheimnis an den für den empfangenden Endpunkt verantwortlichen Entwickler weiter und speichern Sie es an einem sicheren serverseitigen Ort, beispielsweise:

• In einer Umgebungsvariablen.
• In einer verschlüsselten Anwendungskonfiguration.
• In einem Cloud-Geheimnismanager.
• In einem geschützten Anmeldedatenspeicher.

Speichern Sie das Geheimnis nicht in Frontend-JavaScript, öffentlichen Repositorys, Screenshots, gemeinsam genutzten Dokumenten oder Supportnachrichten, auf die unbefugte Benutzer zugreifen können.

 

Einen Webhook testen

Sie sollten jeden Webhook testen, bevor Sie ihn in einem Live-Arbeitsablauf verwenden.

Eine Testübertragung bestätigt, dass der Endpunkt erreichbar ist und der empfangende Server eine geeignete Antwort zurückgibt.

Schritt 1: Webhook suchen

Suchen Sie das Webhook-Abonnement in der Übersicht der Standard-Webhooks.

Schritt 2: Testübertragung senden

Klicken Sie in der Webhook-Zeile auf das Blitzsymbol.

Enquete sendet eine Testanfrage an den konfigurierten Endpunkt.

Schritt 3: Ergebnis überprüfen

Eine Inline-Benachrichtigung zeigt den vom Endpunkt zurückgegebenen HTTP-Status an.

Eine erfolgreiche Übertragung gibt normalerweise einen Statuscode im Bereich von 200 bis 299 zurück, zum Beispiel:

• 200 OK
• 201 Created
• 202 Accepted
• 204 No Content

Wenn der Test fehlschlägt, öffnen Sie die Übertragungsprotokolle, um den Antwortstatus, den Antworttext, Fehlerinformationen und die Anfragedauer zu überprüfen.

 

Einen Webhook bearbeiten

Sie können einen vorhandenen Webhook aktualisieren, wenn sich sein Endpunkt, seine Umfrage, sein Ereignistyp, seine Beschreibung oder sein Aktivierungsstatus ändert.

Schritt 1: Auf Bearbeiten klicken

Suchen Sie den Webhook und wählen Sie die Aktion Bearbeiten aus.

Schritt 2: Einstellungen aktualisieren

Sie können unter anderem folgende Einstellungen aktualisieren:

• Die Endpunkt-URL.
• Die Webhook-Beschreibung.
• Die ausgewählte Umfrage.
• Den Ereignistyp.
• Den aktiven oder inaktiven Status.

Schritt 3: Änderungen speichern

Speichern Sie den Webhook, nachdem Sie Ihre Änderungen vorgenommen haben.

Die aktualisierte Konfiguration wird für zukünftige Übertragungen verwendet.

Senden Sie immer eine weitere Testübertragung, nachdem Sie die Endpunkt-URL, die Umfrage oder den Ereignistyp geändert haben.

 

Übertragungsprotokolle anzeigen

Die Übertragungsprotokolle zeigen die Anfragen, die Enquete an Ihren Endpunkt gesendet hat, sowie die Antworten, die vom empfangenden Server zurückgegeben wurden.

Verwenden Sie diese Protokolle, um den Zustand Ihrer Integration zu überwachen und fehlgeschlagene Übertragungen zu untersuchen.

Schritt 1: Protokolle öffnen

Suchen Sie das Webhook-Abonnement und klicken Sie neben der Schaltfläche zum Löschen auf das Symbol „Protokolle anzeigen“.

Schritt 2: Übertragungsverlauf filtern

Sie können Übertragungen nach folgenden Kriterien filtern:

• Alle
• Erfolgreich
• Fehlgeschlagen

Schritt 3: Übertragung prüfen

Erweitern Sie einen Übertragungseintrag, um die verfügbaren Diagnoseinformationen zu überprüfen.

Der Übertragungsdatensatz kann Folgendes enthalten:

• Die Anfrage-Payload.
• Den HTTP-Antwortstatus.
• Den vom empfangenden Server zurückgegebenen Antworttext.
• Eine Fehlermeldung.
• Die Übertragungsdauer in Millisekunden.
• Die Nummer des Übertragungsversuchs.
• Die eindeutige Übertragungs-ID.

Übertragungsprotokolle sind besonders nützlich nach:

• Dem Erstellen eines neuen Webhooks.
• Dem Ändern einer Endpunkt-URL.
• Dem Bereitstellen eines Updates für die empfangende Anwendung.
• Dem Ändern von Firewall- oder Servereinstellungen.
• Der Untersuchung fehlender Umfragedaten.
• Der Untersuchung langsamer oder fehlgeschlagener Übertragungen.

 

Webhook-Header verstehen

Jede Webhook-Anfrage enthält Header, mit denen die empfangende Anwendung die Übertragung identifizieren, überprüfen und nachverfolgen kann.

Header	Beschreibung
X-Enquete-Signature	Enthält die Signatur, mit der überprüft wird, ob die Anfrage von Enquete stammt.
X-Enquete-Event	Identifiziert den Ereignistyp, der die Übertragung ausgelöst hat.
X-Enquete-Delivery	Enthält eine eindeutige Übertragungs-ID, die zur Nachverfolgung und Vermeidung doppelter Verarbeitung verwendet wird.

Ihr technisches Team sollte den Signatur-Header zur Authentifizierung eingehender Anfragen und den Übertragungs-Header verwenden, um zu verhindern, dass dasselbe Ereignis mehr als einmal verarbeitet wird.

Das genaue Signaturformat, das Payload-Schema und Implementierungsbeispiele finden Sie in der offiziellen Webhook-Dokumentation.

 

Doppelte Übertragungen verstehen

Eine Webhook-Übertragung kann mehrmals versucht werden, wenn die erste Anfrage fehlschlägt, eine Zeitüberschreitung auftritt oder keine erfolgreiche Antwort zurückgegeben wird.

Das bedeutet, dass die empfangende Anwendung eine bereits verarbeitete Übertragung erkennen und sicher ignorieren können muss.

Jede Anfrage enthält einen eindeutigen Wert im Header X-Enquete-Delivery.

Ihr technisches Team sollte diesen Wert als Idempotenzschlüssel verwenden.

Ein typischer Prozess zur Vermeidung doppelter Verarbeitung sieht folgendermaßen aus:

1. Lesen Sie den Wert von X-Enquete-Delivery.
2. Prüfen Sie, ob die Übertragungs-ID bereits verarbeitet wurde.
3. Wenn sie bereits verarbeitet wurde, geben Sie eine erfolgreiche Antwort zurück, ohne die Aktion erneut auszuführen.
4. Wenn sie noch nicht verarbeitet wurde, speichern Sie die Übertragungs-ID und verarbeiten Sie das Ereignis.

Verarbeitete Übertragungs-IDs sollten für einen Zeitraum aufbewahrt werden, der den Integrations- und Wiederholungsrichtlinien Ihrer Organisation entspricht.

 

Einen Webhook deaktivieren

Deaktivieren Sie einen Webhook, wenn Sie Übertragungen vorübergehend stoppen möchten, ohne seine Konfiguration zu löschen.

Sie können einen Webhook deaktivieren, während:

• Die empfangende Anwendung gewartet wird.
• Ihr technisches Team den Endpunkt ersetzt.
• Der verbundene Arbeitsablauf vorübergehend pausiert ist.
• Sie wiederholte Fehler untersuchen.
• Der Webhook derzeit nicht benötigt wird.

Wenn der Webhook erneut aktiviert wird, können zukünftige passende Ereignisse übertragen werden.

Ereignisse, die auftreten, während der Webhook inaktiv ist, werden möglicherweise später nicht automatisch übertragen.

 

Einen Webhook löschen

Löschen Sie einen Webhook, wenn das Abonnement nicht mehr benötigt wird.

Schritt 1: Löschen auswählen

Suchen Sie den Webhook und klicken Sie auf die Aktion Löschen.

Schritt 2: Löschen bestätigen

Bestätigen Sie, dass Sie das Webhook-Abonnement dauerhaft entfernen möchten.

Nach dem Löschen sendet Enquete keine neuen Übertragungen mehr für diesen Webhook.

Historische Übertragungsdatensätze können für Prüfungs-, Fehlerbehebungs- oder Betriebszwecke in Backend-Datensätzen verfügbar bleiben.

Wichtig: Wenn Sie den Webhook nur vorübergehend pausieren möchten, deaktivieren Sie ihn, anstatt ihn zu löschen.

 

Fehlerbehebung bei Standard-Webhooks

Die Webhook-Übertragung schlägt fehl oder läuft in eine Zeitüberschreitung

Prüfen Sie Folgendes:

• Bestätigen Sie, dass der Endpunkt öffentlich zugänglich ist.
• Bestätigen Sie, dass der Endpunkt HTTPS verwendet.
• Prüfen Sie, ob eine Firewall- oder Sicherheitsregel die Anfrage blockiert.
• Bestätigen Sie, dass der Endpunkt HTTP-POST-Anfragen akzeptiert.
• Stellen Sie sicher, dass der empfangende Server schnell antwortet.
• Überprüfen Sie die Übertragungsprotokolle auf den Antwortstatus und die Fehlermeldung.
• Bestätigen Sie, dass die empfangende Anwendung derzeit verfügbar ist.

Lang laufende Aufgaben sollten für die Hintergrundverarbeitung in eine Warteschlange gestellt werden, anstatt vollständig ausgeführt zu werden, bevor der Server seine Antwort zurückgibt.

Die Webhook-Signatur ist ungültig

Bitten Sie Ihr technisches Team zu bestätigen, dass:

• Das Geheimnis zum richtigen Webhook-Abonnement gehört.
• Der unveränderte Anfragekörper für die Signaturprüfung verwendet wird.
• Der JSON-Körper vor der Überprüfung nicht neu formatiert wird.
• Das erwartete Signaturformat mit dem von Enquete dokumentierten Format übereinstimmt.

Die Signaturprüfung ist eine technische Implementierungsaufgabe. Die aktuellen Anweisungen zur Verifizierung finden Sie in der offiziellen Webhook-Dokumentation.

Es werden keine Webhook-Übertragungen empfangen

Prüfen Sie Folgendes:

• Stellen Sie sicher, dass der Webhook aktiv ist.
• Bestätigen Sie, dass die richtige Umfrage ausgewählt ist.
• Bestätigen Sie, dass das ausgewählte Ereignis tatsächlich eingetreten ist.
• Prüfen Sie, ob die Endpunkt-URL korrekt ist.
• Senden Sie eine Testübertragung.
• Öffnen Sie die Übertragungsprotokolle, um zu bestätigen, ob eine Anfrage versucht wurde.

Der Endpunkt gibt eine 401- oder 403-Antwort zurück

Eine 401- oder 403-Antwort bedeutet normalerweise, dass der empfangende Server die Anfrage aufgrund einer Authentifizierungs- oder Autorisierungsregel abgelehnt hat.

Prüfen Sie, ob:

• Der Endpunkt eine nicht unterstützte Authentifizierungsmethode erfordert.
• Eine Firewall oder ein API-Gateway die Anfrage ablehnt.
• Der Endpunkt nur Anfragen aus ausgewählten Netzwerken akzeptiert.
• Der Signaturprüfungsprozess gültige Anfragen fälschlicherweise ablehnt.

Der Endpunkt gibt eine 404-Antwort zurück

Eine 404-Antwort bedeutet normalerweise, dass die Endpunkt-URL keiner verfügbaren Route auf dem empfangenden Server entspricht.

Prüfen Sie die vollständige URL und bestätigen Sie, dass die Route vorhanden ist und HTTP-POST-Anfragen akzeptiert.

Der Endpunkt gibt eine 500-Antwort zurück

Eine 500-Antwort weist darauf hin, dass innerhalb der empfangenden Anwendung ein Fehler aufgetreten ist.

Ihr technisches Team sollte die Serverprotokolle der empfangenden Anwendung zusammen mit der in Enquete angezeigten Übertragungs-Payload und Übertragungs-ID überprüfen.

Dasselbe Ereignis wird mehr als einmal verarbeitet

Webhook-Anfragen können nach Fehlern oder Zeitüberschreitungen erneut versucht werden.

Ihr technisches Team sollte den Wert X-Enquete-Delivery verwenden, um Übertragungen zu identifizieren, die bereits verarbeitet wurden.

 

Bewährte Sicherheitspraktiken für Webhooks

• Verwenden Sie immer einen HTTPS-Endpunkt.
• Überprüfen Sie die Webhook-Signatur, bevor Sie eine Anfrage verarbeiten.
• Speichern Sie das Webhook-Geheimnis nur in sicheren serverseitigen Systemen.
• Legen Sie das Geheimnis niemals im Frontend-Code offen.
• Verwenden Sie bei der Signaturprüfung den unveränderten Anfragekörper.
• Verwenden Sie die Übertragungs-ID, um doppelte Verarbeitung zu verhindern.
• Geben Sie schnell eine erfolgreiche Antwort zurück.
• Verarbeiten Sie lang laufende Vorgänge asynchron.
• Überwachen Sie fehlgeschlagene Übertragungen und ungewöhnlich langsame Antworten.
• Überprüfen Sie die Übertragungsprotokolle nach der Bereitstellung von Endpunkt-Updates.
• Testen Sie den Webhook nach jeder Konfigurationsänderung.
• Deaktivieren Sie Webhook-Abonnements, die vorübergehend nicht verwendet werden.
• Löschen Sie Abonnements, die nicht mehr benötigt werden.

 

Checkliste vor der Aktivierung eines Webhooks

Bevor Sie einen Standard-Webhook in einem Live-Arbeitsablauf verwenden, bestätigen Sie, dass Sie Folgendes abgeschlossen haben:

1. Erstellen Sie den Webhook mit dem richtigen HTTPS-Endpunkt.
2. Wählen Sie die richtige Umfrage aus.
3. Wählen Sie den richtigen Ereignistyp aus.
4. Kopieren Sie das Webhook-Geheimnis und speichern Sie es sicher.
5. Implementieren Sie die Signaturprüfung auf dem empfangenden Server.
6. Implementieren Sie einen Schutz vor doppelten Übertragungen.
7. Senden Sie eine Testübertragung.
8. Bestätigen Sie, dass der Endpunkt eine erfolgreiche Antwort zurückgibt.
9. Überprüfen Sie die Anfrage- und Antwortdetails in den Übertragungsprotokollen.
10. Richten Sie Überwachung und Fehlerbenachrichtigungen für den empfangenden Endpunkt ein.
11. Aktivieren Sie den Webhook für Live-Umfrageereignisse.

Nachdem der Webhook live geschaltet wurde, sollten Sie fehlgeschlagene Übertragungen und die Leistung des Endpunkts regelmäßig überprüfen, um sicherzustellen, dass die Integration weiterhin ordnungsgemäß funktioniert.

Informationen zu Payload-Feldern, Ereignisschemata, Beispielen zur Signaturprüfung und weiteren entwicklerspezifischen Anweisungen finden Sie stets in der offiziellen Enquete-Webhook-Dokumentation.