Webhook API-Dokumentation für DSRs

Allgemein

Die Kertos-Plattform bietet Unterstützung zum Senden einer Benachrichtigung für eine empfangene Anfrage von betroffenen Personen über einen Webhook. Um einen Webhook in Kertos integrieren zu können, muss der Endpunkt in der Lage sein, eine Anforderungs-Payload zu verarbeiten, die dem folgenden Interface entspricht:

{
  "data_subject_identifier": string,
  "operation": "read" | "delete",
  "received_at": string <date-time>
}

Die Payload enthält drei Schlüssel:

• data_subject_identifier

• operation

• received_at

Das data_subject_identifier Feld ist ein eindeutiger String, der verwendet wird, um zu identifizieren, welches Datensubjekt eine Anfrage gestellt hat. In den meisten Fällen ist der Bezeichner die E‑Mail‑Adresse des Anfragenden. Das operation Feld, das entweder den Wert "read" oder "delete" wird verwendet, um anzugeben, ob der Webhook erwartungsgemäß alle Informationen, die für das Datensubjekt gefunden wurden, zurückgeben soll (read) oder ob er alle mit dem genannten Datensubjekt verbundenen Informationen löschen soll (delete). Das Feld received_at enthält einen ISO‑8601‑Datums‑Zeit‑String, der angibt, wann die Anfrage empfangen wurde.

Authentifizierung

Für die Authentifizierung wird ein headerbasierter Ansatz verwendet. Die Kertos-Plattform sendet einen API-Key, der in der Webhook-Konfiguration in Kertos angegeben ist, über einen Header namens X-API-KEY . Der Webhook muss prüfen, ob der API-Key korrekt ist, und mit dem entsprechenden Statuscode reagieren, wie im Abschnitt „HTTP Response Codes“ beschrieben.

Beispielanfragen

Sobald in Kertos eine neue Anfrage erstellt wird, sendet die Webhook-Integration eine POST-Anfrage an die in Kertos für deinen Webhook konfigurierte URL:

POST https://api.yourdomain.com/webhooks/gdpr/

Das folgende Anfrage-Payload würde anzeigen, dass jane.miller@kertos.io am 24.08.2024 um 14:15:22 eine Löschanfrage gestellt hat und entsprechend aus dem Empfängersystem des Webhooks gelöscht werden sollte.

{
  "data_subject_identifier": "jane.miller@kertos.io",
  "operation": "delete",
  "received_at": "2024-08-24T14:15:22Z"
}

HTTP-Antwortcodes

Die folgenden HTTP-Statuscodes können von deinem Webhook gesendet werden, um Kertos anzuzeigen, dass etwas schief gelaufen ist:

200 OK
Sollte verwendet werden, um anzuzeigen, dass die angeforderte Operation erfolgreich durchgeführt wurde

401 Access token is missing or invalid
Sollte verwendet werden, um anzuzeigen, dass Authentifizierungsinformationen entweder fehlen oder inkorrekt sind

404 Datensubjekt nicht gefunden
Sollte verwendet werden, um anzuzeigen, dass kein Datensubjekt gefunden werden konnte, das dem bereitgestellten Datensubjekt-Identifikator entspricht.

422 Unverarbeitbare Entität, etwas ist mit dem gesendeten Objekt falsch
Sollte verwendet werden, um anzuzeigen, dass die Eingabe fehlerhaft ist.

Webhook-Einrichtung

So kannst du den Webhook in Kertos aktivieren:

1. In Kertos, gehe zu „Systeme“.

2. Klicke auf „System hinzufügen“.

3. Suche nach „Webhook-Aufruf“ und wähle aus der Liste der verfügbaren Systeme aus.

4. Im Systemdetail, scrolle nach unten zu Request Automation.

5. Klicke "Automatisierung erlauben" und gebe Details an.

6. Speicher das System.