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 registrieren und Webhook-URL ändern
- Nutzersicht auf registrierte Datenweitergabe
- Webhook-URL ändern
- Webhook löschen
- Webhooks auflisten
Derzeit verfügbare Webhooks
Webhook-Key | Benötigter Endpunkt | Beschreibung |
personalData | Personal 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