Ein Webhook sendet Übermittlungsdaten automatisch an ein externes System, sobald ein Mitarbeiter Ihr Formular übermittelt. Dadurch muss niemand die Daten manuell exportieren, importieren oder erneut eingeben. In Kombination mit einem Integrationsdienst, den Ihr technisches Team erstellt, kann ein Webhook einen Workflow in einem anderen System auslösen. Beispielsweise können ein Formular für einen Vorfallbericht, eine HR-Anfrage oder eine Kostenerstattung direkt in Ihr Ticket-, HR- oder Kostenerstattungssystem übermittelt werden.
Jeder Webhook enthält ein Authentifizierungsgeheimnis, sodass das empfangende System bestätigen kann, dass eine Anfrage aus Ihrer Staffbase-Umgebung stammt. Informationen dazu, wie Sie zwischen einem Webhook, E-Mail-Benachrichtigungen und einer Empfängerfrage entscheiden, finden Sie unter Auswählen, wie Übermittlungsdaten weitergeleitet werden.
Funktionsweise des Webhooks
Eine Übermittlung löst ein Webhook-Ereignis aus. Staffbase sendet das Ereignis als POST-Anfrage mit einem JSON-Body an Ihren HTTPS-Endpunkt. Die Nutzlast enthält die Antwortdaten und alle Metadaten, die Sie aus Benutzerprofilfeldern erfassen möchten, einschließlich Systemfeldern und Feldern, die für Ihre Organisation angepasst wurden.
Wenn eine Übermittlung fehlschlägt, versucht Staffbase erneut, die Anfrage an Ihren Endpunkt zu senden.
Informationen zum Hinzufügen eines Webhooks zu einem Formular finden Sie unter Verwenden der Formulareinstellungen. Nachdem Sie ihn hinzugefügt haben, wählen Sie die drei Punkte neben dem Webhook aus, um ihn zu testen, zu bearbeiten oder zu löschen:
- Übermittlungen: Wählen Sie Test senden, um ein Testereignis zu senden. Die Übermittlungs-ID und der Antwortstatuscode werden angezeigt. Testübermittlungen sind als Test gekennzeichnet.
- Bearbeiten: Ändern Sie die Webhook-URL oder kopieren bzw. generieren Sie das Geheimnis neu. Bewahren Sie nach der Neugenerierung eines Geheimnisses das vorherige Geheimnis und seine Schlüssel-ID auf, bis ältere Übermittlungen abgeschlossen sind, da Wiederholungsversuche für diese Ereignisse weiterhin das alte Geheimnis verwenden.
- Löschen: Entfernen Sie den Webhook. Sie werden in einer Warnung aufgefordert, den Vorgang zu bestätigen.
Grundlegendes zur Webhook-Nutzlast
Die JSON-Nutzlast enthält die folgenden Informationen:
-
Installations-ID des Formulars: Die eindeutige Kennung Ihres Formulars. Um sie im Studio zu finden, öffnen Sie das Aktionsmenü des Formulars und wählen Sie Link kopieren. Die ID ist der letzte Teil der URL:
https://<your-environment>/content/staffbase.forms/<form-installation-ID> - Formulartitel: Der Name des Formulars. Der Titel ist keine eindeutige Kennung.
- Übermittlungs-ID: Die eindeutige Kennung einer Übermittlung. Jede Übermittlung hat einen anderen Wert, auch wenn derselbe Mitarbeiter das Formular mehrmals übermittelt.
- Daten der antwortenden Person: Die Benutzerprofilinformationen, die zusammen mit der Antwort erfasst werden. Standardmäßig sind dies der Vor- und Nachname. Sie können zusätzliche Profilfelder in den Formulareinstellungen unter Daten der antwortenden Person erfassen. Wenn das Formular vertrauliche Antworten verwendet, werden keine Benutzerinformationen eingeschlossen.
-
Antworten: Die Antworten auf die beantworteten Fragen. Jede Antwort enthält
questionIdundquestionLabel. Wenn Sie einen Frageschlüssel konfigurieren, enthält die Antwort außerdemquestionKey.
Konfigurieren eines Frageschlüssels
Ein Frageschlüssel erleichtert das Lesen und Zuordnen der Nutzlast im empfangenden System. Ein Frageschlüssel muss mit einem Kleinbuchstaben beginnen, darf nur Kleinbuchstaben, Zahlen und Unterstriche enthalten und höchstens 64 Zeichen lang sein. Schlüssel müssen innerhalb des Formulars eindeutig sein, einschließlich der Schlüssel gelöschter Fragen.
- Öffnen Sie das Formular im Editor.
- Wählen Sie eine Frage und anschließend das Stiftsymbol aus, um die Frageeinstellungen zu öffnen.
- Geben Sie den Frageschlüssel ein.
- Veröffentlichen oder aktualisieren Sie das Formular, damit die Änderung wirksam wird.
Bereits in die Warteschlange eingereihte Übermittlungen behalten ihre ursprünglichen Schlüssel.
Sichern Ihres Webhooks
Wenn Sie einen Webhook überwachen, machen Sie eine URL im Internet zugänglich. Staffbase signiert jede Nutzlast mit Ihrem Webhook-Geheimnis, damit Ihr System vor der Verarbeitung überprüfen kann, ob eine Anfrage authentisch ist. So überprüfen Sie eine Anfrage:
- Lesen Sie die Anfrage-Header
X-Staffbase-Webhook-Timestamp,X-Staffbase-Webhook-Delivery-Id,X-Staffbase-Webhook-Key-IdundX-Staffbase-Webhook-Signature. - Dekodieren Sie das Geheimnis aus base64url in Bytes.
-
Berechnen Sie HMAC-SHA256 über das folgende UTF-8-Präfix, gefolgt von den exakten, unveränderten Bytes des Anfrage-Bodys:
v1.<timestamp>.<deliveryId>.<keyId>.
- Kodieren Sie das Ergebnis ohne Padding als base64url, stellen Sie ihm
v1=voran und vergleichen Sie es mithilfe eines zeitkonstanten Vergleichs mit dem Signatur-Header.
Staffbase empfiehlt für Ihren Empfänger die folgenden zusätzlichen Schutzmaßnahmen:
- Überprüfen Sie die Aktualität des Zeitstempels, beispielsweise mit einer Toleranz von fünf Minuten. Der Zeitstempel wird in Unix-Sekunden angegeben.
- Lehnen Sie wiederholt verwendete Übermittlungs-IDs ab.
- Behandeln Sie Wiederholungsversuche idempotent. Jeder Wiederholungsversuch hat eine neue Übermittlungs-ID, aber dieselbe
X-Staffbase-Webhook-Id. Wenn Sie dieses Ereignis bereits verarbeitet haben, geben Sie eine 2xx-Antwort zurück, ohne es erneut zu verarbeiten.
Kommentare
0 Kommentare
Bitte melden Sie sich an, um einen Kommentar zu hinterlassen.