Configure Pre Approval Webhooks

What is a Pre Approval webhook?

A pre-approval webhook is an HTTPS callback that calls an external REST API endpoint as soon as a privacy request is received (or after user identity verification, if that is configured).

The response(s) to the callback allow us to determine whether or not the privacy request is eligible to be automatically approved. If all webhooks respond with eligible, we can automatically approve the privacy request for execution, otherwise we leave the privacy request in pending, awaiting manual approval in Admin UI.

If a privacy request is waiting for manual approval, Fides waits until one of the conditions are met:

1. All configured pre-approval webhooks have responded with eligible --> Fides automatically approves request and queues request to run.
2. The privacy request is manually approved in the Admin UI --> Fides queues request to run.

Note that Fides processes privacy requests immediately by default. To review privacy requests before they are executed, the require_manual_request_approval variable in your fides.toml must be set to TRUE. This is required to trigger and process pre-approval webhooks.

Configuration

The process below will define an https Connection that contains the details to make a request to your API endpoint, and then create a PreApprovalWebhook using that Connection.

Create an HTTPS Connection

The information that describes how to connect to your API endpoint is represented by a Fides Integration.

[
    {
      "name": "My Service Config",
      "key": "my_service_config",
      "connection_type": "https",
      "access": "read"
    }
]

Add your Connection secrets

The credentials needed to access your API endpoint are defined by making a PUT to the Connection Secrets endpoint. These credentials are encrypted in the Fides app database.

    {
        "url": "https://www.example.com/fides-webhook",
        "authorization": "test_authorization"
    }

Define pre-approval webhooks

After you've defined a new Connection, you can create lists of webhooks to run as soon as a privacy request is received.

To create a list of PreApprovalWebhooks:

[
   {
      "connection_config_key":"my_service_config",
      "name":"My test webhook",
      "key":"my_test_webhook"
   },
   {
      "connection_config_key":"my_other_service_config",
      "name":"My test webhook 2",
      "key":"my_test_webhook_2"
   }
]

This creates two webhooks that will both run as soon as a privacy request is created.

This means your my_service_config will receive an API call from Fides at https://www.example.com/fides-webhook (or whatever URL / path you have set in your Connection Config). Same with your my_other_service_config.

Update a single webhook

To update a single webhook, send a PATCH request to update selected attributes.

The following example will update the PreApprovalWebhook with key my_test_webhook to be Some other name instead of My test webhook.

{
    "name": "Some other name"
}

Webhook request format

Before and after running access or erasure requests, Fides will send requests to any configured webhooks with the following request body:

{
  "privacy_request_id": "pri_029832ba-3b84-40f7-8946-82aec6f95448",
  "privacy_reqeust_status": "pending",
  "direction": "two_way", // this is always two_way for pre-approval webhooks, but could be one_way for other webhook types
  "callback_type": "pre_approval",
  "identity": {
    "email": "customer-1@example.com",
    "phone_number": "555-5555"
  },
  "policy_action": "access | consent | erasure | update"
}

These attributes were configured at the time of webhook creation. Known identities are also embedded in the request.

Fides includes specific headers including data needed to respond to the webhook:

{
  "reply-to-approve": "/privacy-request/{privacy_request_id}/pre-approve/eligible",
  "reply-to-deny": "/privacy-request/{privacy_request_id}/pre-approve/not-eligible",
  "reply-to-token": "<jwe_token>"
}

Responding to the webhook

You have 2 options to respond to the webhook:

1. If your service has determined the privacy request is eligible to be automatically approved, send a request to the reply-to-approve URL sent in the original request header, along with the reply-to-token auth token.
2. If your service has determined the privacy request is not eligible to be automatically approved, send a request to the reply-to-deny URL sent in the original request header, along with the reply-to-token auth token.

Send an empty {} request body.

For example, to mark the privacy request as eligible:

POST /privacy-request/{privacy_request_id}/pre-approve/eligible with Authorization: Bearer {reply_to_token}

All configured webhooks must respond with eligible in order for any given privacy request to be automatically approved.