In der Third Party API können Webhooks registriert werden. Webhooks dienen dazu bei bestimmten Ereignissen Datensätze (JSON - Objekte) an eine zuvor definierte URL zu schicken. Das Format der Daten ist dabei fest vorgegeben, der Drittanbieter muss unter der angegebenen URL einen Listener bereit stellen, der die Daten entgegennimmt. 


Webhooks können an jedem Endpunkt mit der gleichen Syntax registriert werden. Ob ein Webhook registriert werden kann hängt vom gebuchten Endpunkt ab. Das Registrieren (und Löschen) von Webhooks zählt nicht ins Rate-Limit. 


Webhooks können derzeit nur über API - Keys angelegt werden, nicht über Clients!



INHALTSVERZEICHNIS



Derzeit verfügbare Webhooks


Webhook-KeyBenötigter EndpunktBeschreibung
personalDataPersonal
Endpunkte Personal
Gibt ein User von LINA seine Daten für einen Drittanbieter frei, werden bestimmte persönliche Daten des Users an die registrierte Webhook-URL gesandt.





Webhook registrieren und Webhook-URL ändern

Ein Webhook kann an jedem Endpunkt registriert werden. Soll z.B. der Endpunkt "Personal" genutzt werden, ist die URL für das Registrieren eines Webhooks:

https://app.lina.de/extern/personal/registerWebhook


als Payload (POST, rawBody) muss ein JSON - Objekt mit dem Webhook-Key und der eigenen Webhook-URL des Anbieters mitgegeben werden, auf der der Listener läuft: 



 

{
    "hookKey": "personalData",
    "url": "http://127.0.0.1:5559/personalDataRegistered"
}


Als Antwort erhält man beide Felder zusammen mit einer uuid für diesen Webhook: 


{
    "hookKey": "personalData",
    "url": "http://127.0.0.1:5559/personalDataRegistered",
    "uuid": "48138367-3eba-4772-b2bf-6bbd11840efb"
}
Diese uuid sollte man unbedingt bei sich ablegen, sie gilt als Referenz für alle Daten, die an diese URL geschickt werden.


Über diese uuid kann also z.B. am eigenen Endpunkt der entsprechende Betrieb identifiziert werden. 


Nutzersicht auf registrierte Datenweitergabe


tbd: screenshot Nutzer > meine Daten > ... 


Webhook-URL ändern


Die Webhook-URL wird bearbeitet , indem man das Antwortobjekt mit einer neuen URL und der zuvor registrierten eindeutigen uuid dieses Webhooks schickt: 


{
    "hookKey": "personalData",
    "uuid": "48138367-3eba-4772-b2bf-6bbd11840efb",
    "url": "http://127.0.0.1:5559/personalDataRegistered2"
}

... würde die URL für den bestehenden Webhook mit eindeutiger uuid ändern. 



Webhook löschen


Um einen Webhook zu löschen, wird ein Request an 

https://app.lina.de/extern/personal/registerWebhook

mit dem Payload Webhook-URL und die Webhook-uuid als JSON-Opjekt geschickt.


{
    "hookKey": "personalData",
    "uuid": "48138367-3eba-4772-b2bf-6bbd11840efb"
}


Der Webhook wird dadurch vollständig entfernt, Webhook-URL und die Webhook-uuid gelöscht.


Webhooks auflisten

Alle für einen Laden (durch einen Operator) registrierten Webhooks kann man auflisten: 


https://app.lina.de/extern/personal/listWebhook