Webhook API Docs for DSRs

General

The Kertos platform offers support to send a notification for a received data subject request via webhook. To be able to integrate a webhook into Kertos, the endpoint needs to be able to process a request payload that adheres to the following interface:

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

The payload contains three keys

data_subject_identifier

operation

received_at

The data_subject_identifier field is a unique string used to identify which data subject has issued a request. In most cases, the identifier is the email address of the requester. The operation field, which can either hold the value "read" or "delete" is used to indicate if the the webhook is expected to return all information found for the data subject (read) or if it is expected to delete all information connected to said data subject (delete). The field received_at holds a ISO 8601 date-time string indicating when the request was received.

Authentication

For authentication, a header-based approach is used. The Kertos plattform sends an API-key provided in the webhook-configuration on Kertos using a header called X-API-KEY . The webhook needs to verify if the API-key is correct and respond with the corresponding status code as described in the section “HTTP Response Codes”.

Request samples

Once a new request is created in Kertos, the webhook integration would send a POST request to the URL configured in Kertos for your webhook:

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

The following request payload would indicate that jane.miller@kertos.io has issued a deletion request on the 24.08.2024 at 14:15:22 and should be deleted from the webhook recipient system accordingly.

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

HTTP Response Codes

The following HTTP response codes can be sent by your webhook to indicate to Kertos that something has gone wrong:

200 OK
Should be used to indicate that the requested operation was performed successfully

401 Access token is missing or invalid
Should be used to indicate that authentication information is either missing or incorrect

404 Data subject not found
Should be used to indicate that no data subject could be found that matches the provided data subject indentifier

422 unprocessable entity, something is wrong with the sent object
Should be used to indicate that the input is malformed