Webhook Konfigurator

Inhaltsverzeichnis

1. Einleitung
2. Webhook Konfigurator
3. Neuen Webhook erstellen
4. Webhook-Requests

 

1. Einleitung

Was ist ein Webhook?

Mit Webhooks (zusammengesetzt aus „Web“ und „Hook“, zu deutsch etwa Web-Haken) wird ein nicht-standardisiertes Verfahren zur Kommunikation von Servern bezeichnet, das im Rahmen des verteilten Rechnens oder der Nachrichtenorientierten Middleware genutzt wird. Webhooks ermöglichen es, einer Server-Software mitzuteilen, dass ein bestimmtes Ereignis eingetreten ist und eine Reaktion auf das Ereignis auszulösen. Wenn eine Anwendung über ein eingetretenes Ereignis mittels WebHook informiert, müssen an dem Ereignis interessierte andere Anwendungen kein Polling (Polling = zyklische Abfragen) betreiben, um von dem Ereignis Kenntnis zu erlangen. Das reduziert das Nachrichtenaufkommen zwischen den Anwendungen.

Webhooks finden als einfaches Callback-Verfahren Verwendung zur Daten-Synchronisation, externen Berechnung und zur Datenvalidierung. Technisch wird dazu eine HTTP-POST-Message an eine dafür vorbereitete URL gesendet, welche die angeforderten Daten zurückliefert.

(Quelle)

Mehrwert

Über Webhooks können Änderungen in HR WORKS an einen Server geschickt werden. Dadurch ist es nicht nötig, in einem bestimmten Rhythmus Daten über die API abzufragen. Um diese aktuell zu halten, sondern Änderungen werden aktiv an einen Server kommuniziert.

Aktueller Beta-Status der Webhooks

Momentan sind Webhooks als Beta-Version in HR WORKS verfügbar. Für die Beta-Phase gelten die folgenden Limitierungen:

• Pro HR WORKS-Account können aktuell maximal 500 Webhooks angelegt werden.
• Webhooks können direkt über die API gelesen, erstellt, geändert und gelöscht werden. 

Diese Aktionen in HR WORKS sind mögliche Auslöser für einen Webhook:

Personen

• Eine Person wird erstellt
• Eine Person wird geändert
• Eine Person wird gelöscht
• Eine Person wird auf ausgeschieden gesetzt

Abwesenheiten

• Eine Abwesenheit wird erstellt
• Eine Abwesenheit wird geändert
• Eine Abwesenheit wird gelöscht

Krankmeldungen

• Eine Krankmeldung wird erstellt
• Eine Krankmeldung wird geändert
• Eine Krankmeldung wird gelöscht

Homeoffice/Mobiles Arbeiten

• Ein Homeoffice-Antrag wird erstellt
• Ein Homeoffice-Antrag wird geändert
• Ein Homeoffice-Antrag wird gelöscht

Bewerber

• Ein Bewerber wird erstellt
• Ein Bewerber wird geändert
• Ein Bewerber wird gelöscht

Eine Erweiterung um weitere Auslöser für Webhooks ist zukünftig geplant. Diese Erweiterung soll anhand von eingehenden Feedbacks geschehen. Daher leiten Sie uns gerne Vorschläge weiter, welche weiteren Aktionen in HR WORKS Sie sich zukünftig im Webhook-Konfigurator wünschen. Die Priorisierung der weiteren Auslöser für Webhooks wird anhand der Anzahl der genannten Vorschläge erfolgen. 

Feedback können Sie in HR WORKS unter “Wie kann HR WORKS verbessert werden?” einreichen.

2. Webhook Konfigurator

Webhooks sind eine Erweiterung der API und können daher nur zusammen mit der HR WORKS-API verwendet werden. Weitere Informationen zur HR WORKS-API finden Sie hier.

Voraussetzung für die Nutzung des Webhook-Konfigurators ist die Administrator-Rolle “API-Administrator”. Mit dieser Rolle finden Sie den Webhook-Konfigurator in der Administrator-Oberfläche unter Grundlagen/Integrationen/Webhook-Konfigurator. Hier haben Sie die Möglichkeit, neue Webhooks zu erstellen und bestehende Webhooks anzupassen. 

Hier gelangen Sie zur technischen Dokumentation der Webhooks.

3. Neuen Webhook erstellen

Um einen neuen Webhook erstellen zu können, klicken Sie im Bereich Webhook-Konfigurator auf “Einen neuen Webhook erstellen”. Anschließend füllen Sie die angegebenen Felder zum Webhook aus. 

Bezeichnung

Geben Sie einem Webhook eine Bezeichnung, um auf einen Blick erkennen zu können, um welchen Webhook es sich handelt.

Auslöser und aufzurufende URL

Der Auslöser beschreibt die Aktion in HR WORKS, bei der die “aufzurufende URL” aufgerufen wird. Im Feld “Auslöser” sehen Sie eine Liste der verfügbaren Aktionen, die momentan verwendet werden können. 

API Credentials

Wie bereits beschrieben ist der Webhook eine Erweiterung der HR WORKS-API. Daher benötigt ein aktiver Webhook auch immer hinterlegte API Credentials. Über die Dropdown-Liste sehen Sie alle aktuell angelegten API Credentials. Wählen Sie die Credentials aus, die Sie für den Webhook verwenden möchten. Falls Ihnen keine Credentials vorliegen, können Sie diese unter Grundlagen/Integration/HR WORKS-API anlegen. Als Best Practice wird empfohlen, bei der Verarbeitung der Requests die Signatur der Credentials zu prüfen.

Aktiv

Mit der Checkbox im Feld “Aktiv” legen Sie fest, oder dieser Webhook aktuell genutzt werden soll. Für den Fall, dass Sie einen Webhook deaktivieren möchten, ihn aber nicht löschen möchten, können Sie diesen Haken entfernen und der Webhook wird anschließend bei der hinterlegten Aktion nicht mehr aufgerufen. 

Bemerkung

Im Feld Bemerkung haben Sie die Möglichkeit Notizen zur Nachvollziehbarkeit und die Begründung für den Webhook festzuhalten. Das Feld ist optional und muss nicht befüllt werden.

4. Webhook-Requests 

Webhook-Requests sind POST-Requests an die hinterlegte Ziel-URL. Die Payload hat dabei die folgende Struktur:

Erläuterung

event: Im Post-Request wird im Falle des Webhooks immer die Antwort “serverEvent” mitgegeben.

resourceLocation: Ist der Link zur erstellten, veränderten oder gelöschten Ressource. Hier im Beispiel ist die Person mit der Personalnummer 2 geändert worden.

jobId: Eine zufällige GUID, die Sie dem HR WORKS-Support bei Problemen mitteilen sollten.

action: gibt die erfolgte Aktion an. Mögliche Aktionen sind das Erstellen (resourceCreated), das Ändern (resourceUpdated) und das Löschen (resourceDeleted).