Webhook Konfigurator

In folgendem Artikel erhalten Sie nähere Informationen über den HRworks 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 HRworks 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 HRworks verfügbar. Für die Beta-Phase gelten die folgenden Limitierungen:

• Pro HRworks-Account können aktuell maximal 20 Webhooks angelegt werden. 
• Diese Aktionen in HRworks sind mögliche Auslöser für einen Webhook:
  • Eine Person wird erstellt
  • Eine Person wird geändert
  • Eine Person wird gelöscht
  • Eine Person wird auf ausgeschieden gesetzt

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 HRworks 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 HRworks unter “Wie kann HRworks verbessert werden?” einreichen.

2. Webhook Konfigurator

Webhooks sind eine Erweiterung der API und können daher nur zusammen mit der HRworks-API verwendet werden. Weitere Informationen zur HRworks-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 HRworks, 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 HRworks-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/HRworks-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 HRworks-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).