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 a pending state, awaiting manual approval in Admin UI.

Why use pre-approval webhooks?

Pre-approval webhooks are useful when you need to integrate external business logic or validation before automatically processing a privacy request. Common use cases include:

• Checking if a customer has an active support ticket or pending transaction that should be resolved first
• Verifying that the requester meets certain criteria in your CRM or customer database
• Integrating with third-party compliance systems that need to review requests
• Applying custom business rules that determine whether a request can be auto-approved

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.

To enable Pre Approval webhooks, the require_manual_request_approval variable must be set to true. This is required to trigger and process pre-approval webhooks. You can find more information about this variable and how set it in the execution configuration variables docs

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 Connection.

[
    {
      "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 and securely stored in Fides.

    {
        "url": "{service-url}/pre-approval-handler",
        "authorization": "test_authorization",
        "headers": { // optional headers to be attached to the request
          "User-Agent": "Example"
        }
    }

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 webhook with the key my_service_config will receive an API call from Fides at {service-url}/pre-approval-handler (or whatever URL / path you have set in your Connection Config). Same with your webhook with the key 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

Fides will send requests to any configured webhooks with the following request body:

{
  "privacy_request_id": "pri_029832ba-3b84-40f7-8946-82aec6f95448",
  "privacy_request_status": "pending",
  "direction": "two_way", // this is always two_way for pre-approval webhooks, meaning your service must use one of the reply paths in the request headers mentioned below
  "callback_type": "pre_approval",
  "identity": {
    "email": "customer-1@example.com",
    "phone_number": "555-5555"
  },
  "policy_action": "access" //  other policy actions are 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 /api/v1/privacy-request/{privacy_request_id}/pre-approve/eligible

Make sure to include the Authorization header: Authorization: Bearer {reply_to_token}

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

Multiple Webhooks

When you have multiple pre-approval webhooks configured, Fides uses an "all must approve" logic:

• If ALL webhooks respond with eligible → The privacy request will be automatically approved and queued for execution
• If ANY webhook responds with not-eligible → The privacy request will remain in a pending state (shown as status "New" in the Privacy Request UI) and require manual approval

This ensures that all your validation systems must agree before a privacy request is automatically processed.

Error Handling

If a webhook fails to respond, times out, or returns an error:

• The privacy request will remain in a pending state (shown as status "New" in the Privacy Request UI) awaiting manual approval
• The webhook failure will be logged for debugging
• Other configured webhooks will still be called and can respond independently
• You can manually approve the request in the Admin UI at any time

This ensures that privacy requests are never automatically approved if any part of your validation logic fails or is unreachable.