As consent and subscription choices, as well as data subject rights requests are sent to the Ketch Platform for storage and propagation to connected third party systems, this same data can also be propagated to first party systems through webhooks.

🚧

Developer Edition Add On Required

In order to access webhooks within the Ketch Platform, you will need to add the developer edition to your subscription. To add the Developer Edition to your package, please contact your account executive, or support to find out how to get access.

Why webhooks

A webhook is an HTTP request, triggered by an event in a source system and sent to a destination system, often with a payload of data.

Ketch uses webhooks to let you applications know when events happen, like a change in user consent preferences. When an event occurs, the Ketch Platform makes an HTTP request to the URL you configured for the webhook.

Event overview

The Ketch Platform supports the following events for webhook integrations are:

  • User consent preference changes
  • User subscription preference changes
  • Data subject rights requests

Some of these events are informational only, like consent and subscription preferences changes, while others require a response because they are part of a Ketch workflow, like performing a data access or data deletion request.

Before a webhook can receive an event, it must first be configured in the Ketch Platform.

Once the webhook has been configured, the Ketch Platform will immediately begin sending the corresponding events to this webhook.

Webhook security

At this time, Ketch webhooks employ a bearer authentication scheme. Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.

This is a requirement for all webhooks created in the Ketch Platform and will be added to the header of every request made to this webhook.

Webhook retry policy

The Ketch Platform will try 3 times to successfully send the request to the webhook in case of server errors occurring on the end point. Ketch implements retries with an exponential backoff.

After the 3rd retry, the Ketch Platform will no longer attempt to send the request to the endpoint.

Webhook protocols

Ketch has defined a set of standardized request and response protocols for webhooks. To see the relevant protocols for the various webhooks, visit the sections below:

DSR webhooks

DSR webhooks are those webhooks marked to receive requests as part of a rights based workflow. A webhook is added to a work flow via an API tile within the workflow builder.

When a user invokes a DSR request, the Ketch Platform kicks off a workflow to fulfill the users request. The users request will progress through the workflow processing the various tasks and once it encounters the API tile task, the Ketch Platform will send the request to the associated endpoint with all the relevant data about the request.

DSR webhook flow

The DSR webhook flow is as follows:

  1. Ketch Platform sends a request to the endpoint configured on the webhook. For each DSR request type, there is a corresponding request object sent.

  2. When the endpoint receives the request from the Ketch Platform, it MUST immediately respond with a 200 OK and the corresponding response object for the request type.

  3. As the endpoint processes the request, it can send back information as status updates to the Ketch Platform with a corresponding status event object to the call back URL from the originating request.

    The results and documents are merged with any cached results from previous events. New documents are added and existing documents are updated.

  4. Upon completion of processing the request, the system must send a final status event with the status set to completed, cancelled, or denied. Once the final status event is sent, no further events will be accepted.

  5. The Ketch Platform will proceed with processing the rest of the workflow.