Skip to main content

Webhooks Overview

Webhook integrations allow Cyera to dispatch privacy request processing to your systems. When a privacy request reaches the appropriate lifecycle stage, Cyera sends an HTTP request to your webhook endpoint with the details needed to perform the work (e.g., retrieve or delete data). Once your system completes the work, it confirms completion via the provided callback URL.

Configure a Webhook Endpoint​

The initial step in setting up a webhook integration involves creating a webhook endpoint. The endpoint will allow Cyera to send notifications about incoming requests. Webhook notifications will be sent as HTTP POST requests with a JSON body to the configured webhook endpoint.

Requests​

Privacy Request Notifications​

As a privacy request progresses through its lifecycle, Cyera dispatches notifications to your webhook endpoint at the appropriate stage. The notification type depends on the work your system needs to perform:

  • Access - Retrieve the data subject's personal data from your system.
  • Deletion - Delete the data subject's personal data from your system.
  • Opt-Out - Process an opt-out request for the data subject.
  • Identifiers - Look up additional identifiers for the data subject in your system.

Health Check​

Cyera periodically sends health check requests to verify that your webhook endpoint is reachable and functioning correctly. Health checks are not associated with any privacy request.

Readiness Check​

When a Readiness Check is configured on the webhook integration, Cyera sends a Readiness Check notification at the appropriate stage of the privacy request lifecycle. Your system must respond to the callback with one of the configured answer options.

Headers​

Cyera will include two custom headers in the webhook request for identification and security purposes.

NameDescription
X-Webhook-SignatureHMAC-SHA256 signature to verify the request originated from Cyera.
X-Webhook-TimestampTimestamp of when the request was sent.
Example Headers
{
  "X-Webhook-Timestamp": "1757462400",
  "X-Webhook-Signature": "kecgzfKH7/rUIns3tA1V4xDo9g/8k+aaClx9osgcpfg=",
  "Accept": "application/json",
  "Content-Type": "application/json",
  "User-Agent": "privacyclient/1.0"
}

Body​

The webhook body will be sent as a JSON object, where the structure of the body will depend on the notification type.

Common Request Body Parameters​

For all webhook requests, the body will contain the following common parameters:

NameDescription
integration_namestring
The integration display name in the Cyera application.
integration_kindstring
The integration kind, which will always be webhook.
webhook_request_idstring(UUID)
A unique identifier for the webhook request.
request_typeenum(RequestType)
The action to perform (privacy request type, or health check).

Health Check Body​

The Health Check notification body will only contain the Common Body Parameters.

Example Body: Health Check
{
  "request_type": "health_check",
  "integration_name": "Webhook Integration",
  "integration_kind": "webhook",
  "webhook_request_id": "3aa32ca6-e60d-4b71-981a-d1ba258fd712"
}

Access and Deletion Body Parameters​

In addition to the Common Body Parameters, the Access and Deletion notification bodies will include the following specific parameters:

NameDescription
topicenum(Topic)
The type of request notification.
identifiersobject(Identifiers)
The data subject identifiers associated with the request.
webhook_callback_urlstring
The URL to callback to once the request is complete.
privacy_request_idstring(UUID)
The UUID of the privacy request (36-character string).
integration_idstring(UUID)
The UUID of the integration (36-character string).
Example Body: Access Request
{
  "request_type": "access",
  "integration_name": "Webhook Integration",
  "integration_kind": "webhook",
  "topic": "privacy_request:create",
  "identifiers": {
    "email": [ { "email": "john@example.com" } ],
    "user_id": [ { "user_id": "100101" } ]
  },
  "webhook_callback_url": "https://acme.privacy.cyera.io/api/v2/webhooks/callback",
  "privacy_request_id": "4b7a02e2-361e-4957-9d69-b381e3f47758",
  "integration_id": "4b7a02e2-361e-4957-9d69-b381e3f47758",
  "webhook_request_id": "3aa32ca6-e60d-4b71-981a-d1ba258fd712"
}

Opt-Out Body Parameters​

In addition to the Common Body Parameters, the Opt-Out notification bodies will include the following specific parameters:

NameDescription
topicenum(Topic)
The type of request notification.
identifiersobject(Identifiers)
The data subject identifier associated with the request.
webhook_callback_urlstring
The URL to callback to once the request is complete.
opt_out_request_idstring(UUID)
The UUID of the opt-out request (36-character string).
integration_state_idinteger
The ID of the opt-out integration.
Example Body: Opt-Out Request
{
  "request_type": "opt_out",
  "integration_name": "Webhook Integration",
  "integration_kind": "webhook",
  "topic": "opt_out:create",
  "identifiers": {
    "email": [ { "email": "john@example.com" } ]
  },
  "webhook_callback_url": "https://acme.privacy.cyera.io/api/v2/webhooks/callback",
  "opt_out_request_id": "206356d2-80de-492c-bd34-b0093b6f5d25",
  "integration_state_id": 123456789,
  "webhook_request_id": "9bfacff3-c454-4212-9417-88e246e1798f"
}

Readiness Check Body Parameters​

In addition to the Common Body Parameters, the Readiness Check notification body will include the following specific parameters:

NameDescription
identifiersobject(Identifiers)
The data subject identifiers associated with the request.
webhook_callback_urlstring
The URL to callback to once the readiness check is complete.
privacy_request_idstring(UUID)
The UUID of the privacy request (36-character string).
integration_idstring(UUID)
The UUID of the integration (36-character string).
questionstring
The question label as configured in the integration settings.
answersstring[]
The two configured answer options (e.g., ["Yes", "No"]).
Example Body: Readiness Check
{
  "request_type": "readiness_check",
  "integration_name": "Webhook Integration",
  "integration_kind": "webhook",
  "identifiers": {
    "email": [ { "email": "john@example.com" } ],
    "user_id": [ { "user_id": "100101" } ]
  },
  "webhook_callback_url": "https://acme.privacy.cyera.io/api/v2/webhooks/callback",
  "privacy_request_id": "80edbafc-4ec6-45a0-b341-73080457890e",
  "integration_id": "7efa58a8-9b7d-4faf-8082-5f7f7f407db7",
  "webhook_request_id": "46093148-5087-423d-81b5-88c22701c642",
  "question": "Is the system ready to process this request?",
  "answers": ["Yes", "No"]
}

Identifier Retrieval Body Parameters​

When the Identifier Retrieval capability is enabled, Cyera sends an identifiers notification to look up identifiers that you have mapped to the integration as an Extracted identifier. In addition to the Common Body Parameters, the notification body includes the following parameters:

NameDescription
topicenum(Topic)
identifiers:create for the first notification, identifiers:reminder for reminders.
identifiersobject(Identifiers)
The data subject identifiers already known for the request.
webhook_callback_urlstring
The URL to callback to once the identifiers are ready.
privacy_request_idstring(UUID)
The UUID of the privacy request (36-character string).
integration_idstring(UUID)
The UUID of the integration (36-character string).
results_tokenstring
A token that identifies this identifier request. Include it in your callback.

Reminders reuse the same results_token as the first notification. Cyera sends reminders only when the integration's Reminder Frequency is not set to Send once.

Example Body: Identifier Retrieval
{
  "request_type": "identifiers",
  "integration_name": "Webhook Integration",
  "integration_kind": "webhook",
  "topic": "identifiers:create",
  "identifiers": {
    "email": [ { "email": "john@example.com" } ]
  },
  "webhook_callback_url": "https://acme.privacy.cyera.io/api/v2/webhooks/callback",
  "privacy_request_id": "4b7a02e2-361e-4957-9d69-b381e3f47758",
  "integration_id": "7efa58a8-9b7d-4faf-8082-5f7f7f407db7",
  "results_token": "9f2c1e4a7b6d4c0f8a31b5d2e7c94a10",
  "webhook_request_id": "3aa32ca6-e60d-4b71-981a-d1ba258fd712"
}

Validation​

For security purposes, we strongly recommend implementing a mechanism to validate the Cyera webhook.

First obtain a Webhook Secret generated by Cyera on the webhook integration connection page.

To validate the webhook request, follow these steps:

  1. Fetch the webhook timestamp from the request header X-Webhook-Timestamp (e.g. $TIMESTAMP).
  2. Fetch the webhook body (e.g. $PAYLOAD).
  3. Concatenate the timestamp and body to a single string (e.g. $TIMESTAMP:$PAYLOAD).
  4. Calculate the HMAC-SHA256 signature for the string, using the Webhook Secret.
  5. Convert the signature to the printable ASCII characters (base64).
  6. Compare the signature with the webhook signature from the request header X-Webhook-Signature.

Here are a few webhook validation examples for the Health Check notification:

#!/bin/bash
trap 'rm -f /tmp/payload.txt /tmp/original_signature.bin /tmp/computed_signature.bin' EXIT

read -p "Enter payload: " PAYLOAD
read -p "Enter timestamp: " TIMESTAMP
read -p "Enter signature: " SIGNATURE
read -sp "Enter secret key: " SECRET_KEY

printf "$TIMESTAMP:$PAYLOAD" > /tmp/payload.txt
printf "$SIGNATURE" | base64 -d > /tmp/original_signature.bin

openssl dgst -sha256 -mac HMAC -macopt key:"$SECRET_KEY" -binary /tmp/payload.txt > /tmp/computed_signature.bin
cmp -s /tmp/original_signature.bin /tmp/computed_signature.bin && printf "\nSignature is valid\n" || printf "\nSignature is not valid\n"

Expected Responses​

Success Responses​

Cyera expects a 201 Created HTTP response when a request has been created successfully. Health checks and reminders should respond with a 200 OK.

Error Responses​

If a request has not been created, Cyera expects an appropriate 4xx or 5xx HTTP response code. An error description is not required, but will aid in request debugging.

Example Response Body: 401 Unauthorized
{
  "error": "Invalid request signature"
}
Example Response Body: 400 Bad Request
{
  "error": "Invalid request type"
}

Callbacks​

Once the request has been processed, you must notify Cyera of completion by sending a callback to the provided Callback URL.

Method​

The callback must be an HTTP PUT request to the provided callback URL.

URL​

The callback URL is included in the webhook_callback_url parameter of the webhook notification body.

API Key​

The callback request must include an API key with the Webhook Callback scope. You can create an API key in Cyera by navigating to Settings > API Keys > Create API Key.

Body​

The webhook callback body will be sent as a JSON object, where the structure of the body will depend on the notification type.

Common Callback Body Parameters​

For all webhook callbacks, the body will contain the following common parameters:

NameDescription
webhook_request_idstring(UUID)
A unique identifier for the webhook request.
request_typeenum(RequestType)
The notification type.
statusenum(Status)
The status of the request.

Access Callback Body Parameters​

Access callback bodies will also include the following fields:

NameDescription
privacy_request_idstring(UUID)
The UUID of the privacy request (36-character string).
integration_idenum(RequestType)
The UUID of the integration (36-character string).
resultsobject(Files or FileRefs) (optional)
List of local or remote files to upload.
warning

If your environment is using a Cyera-hosted cloud storage bucket, you must use the Files response type.

File Upload Limit

Max upload limit of all files is 200 MB.

Example Callback Body: Access Request with Files
{
  "webhook_request_id": "3aa32ca6-e60d-4b71-981a-d1ba258fd712",
  "request_type": "access",
  "privacy_request_id": "4b7a02e2-361e-4957-9d69-b381e3f47758",
  "integration_id": "4b7a02e2-361e-4957-9d69-b381e3f47758",
  "status": "completed",
  "results": {
    "files": [
      { "contacts_data.txt": "cHJpdmFjeSBkYXRhIGZvciBzb21lIHVzZXI=" },
      { "events_data.txt": "cHJpdmFjeSBkYXRhIGZvciBzb21lIHVzZXIgKGV2ZW50cyk=" }
    ]
  }
}
Example Callback Body: Access Request with FileRefs
{
  "webhook_request_id": "3aa32ca6-e60d-4b71-981a-d1ba258fd712",
  "request_type": "access",
  "privacy_request_id": "4b7a02e2-361e-4957-9d69-b381e3f47758",
  "integration_id": "4b7a02e2-361e-4957-9d69-b381e3f47758",
  "status": "completed",
  "results": {
    "file_refs": [
      "api_integration_files_sync/{privacy_request_id_}/{integration_id}/{file}"
    ]
  }
}
Example Callback Body: Access Request with No Results
{
  "webhook_request_id": "3aa32ca6-e60d-4b71-981a-d1ba258fd712",
  "request_type": "access",
  "privacy_request_id": "4b7a02e2-361e-4957-9d69-b381e3f47758",
  "integration_id": "4b7a02e2-361e-4957-9d69-b381e3f47758",
  "status": "completed"
}

Deletion Callback Body Parameters​

Deletion callback bodies will also include the following fields:

NameDescription
privacy_request_idstring(UUID)
The UUID of the privacy request (36-character string).
integration_idenum(RequestType)
The UUID of the integration (36-character string).
Example Callback Body: Deletion Request
{
  "webhook_request_id": "8cf283d3-b9d3-4f93-8195-55948c43d625",
  "request_type": "deletion",
  "privacy_request_id": "9b8d61c7-8432-4e7a-bc2d-7ae17232979c",
  "integration_id": "716cde3d-3136-407a-bb32-dba2b4dcf1d9",
  "status": "completed"
}

Opt-Out Callback​

Opt-out callback bodies will also include the following fields:

NameDescription
opt_out_request_idstring(UUID)
The UUID of the opt-out request (36-character string).
integration_state_idinteger
The ID of the opt-out integration.
Example Callback Body: Opt-Out Request
{
  "webhook_request_id": "9bfacff3-c454-4212-9417-88e246e1798f",
  "request_type": "opt_out",
  "opt_out_request_id": "206356d2-80de-492c-bd34-b0093b6f5d25",
  "integration_state_id": 123456789,
  "status": "complete"
}

Readiness Check Callback​

Readiness Check callback bodies will include the following fields. Note that the status field is not applicable for the readiness_check request type.

NameDescription
privacy_request_idstring(UUID)
The UUID of the privacy request (36-character string).
integration_idstring(UUID)
The UUID of the integration (36-character string).
answerstring
The answer to the readiness check question. The value must match one of the configured answer options (case-insensitive).
Example Callback Body: Readiness Check
{
  "request_type": "readiness_check",
  "webhook_request_id": "46093148-5087-423d-81b5-88c22701c642",
  "privacy_request_id": "80edbafc-4ec6-45a0-b341-73080457890e",
  "integration_id": "7efa58a8-9b7d-4faf-8082-5f7f7f407db7",
  "answer": "Yes"
}

Identifier Retrieval Callback​

Identifier Retrieval callback bodies will include the following fields. Unlike other callbacks, they are matched to the request by results_token, and status must be completed.

NameDescription
results_tokenstring
The results_token from the identifiers notification.
identifiersobject (optional)
The identifiers found, keyed by identifier name. Each value is an array of objects. Only the first value in each object is used.

Keys in identifiers must match the identifier names you configured in Cyera. Identifiers that don't match a configured name are ignored. If you don't include identifiers, the request continues without new identifiers.

Example Callback Body: Identifier Retrieval
{
  "request_type": "identifiers",
  "webhook_request_id": "3aa32ca6-e60d-4b71-981a-d1ba258fd712",
  "results_token": "9f2c1e4a7b6d4c0f8a31b5d2e7c94a10",
  "status": "completed",
  "identifiers": {
    "user_id": [ { "user_id": "100101" } ]
  }
}

Expected Responses​

Status CodeDescription
200 OKThe callback was processed successfully.
400 Bad RequestThe request is malformed or contains invalid data (e.g., undecodable Base64 file content).
404 Not FoundThe specified privacy_request_id, integration_id, opt_out_request_id, integration_state_id, or results_token could not be found.
409 ConflictThe integration has already been processed for this request, or the readiness check has expired. No further action is needed.
422 UnprocessableThe request body failed validation (e.g., missing required fields or invalid status / request_type values).

For full API details, see the API documentation for updating a privacy request integration.

Schema​

Objects​

Identifiers​

An object containing key-value pairs of all identifiers for the request.

NameDescription
<identifier_api_name>[]object(Identifier)
The key-value pairs of the identifier category and identifier value.

Identifier​

An individual identifier object.

NameDescription
<identifier_category_key>string
The identifier value of the identifier category.
Identifier Categories and Subcategories

Cyera integrations support the following identifier categories and subcategories:

CategoryCategory KeyDescription
Advertising IDadvertising_idDevice ID used for Ad-based purposes.

Subcategory keys:
  • iOS: ios_advertising_id
  • Google: android_advertising_id
  • Amazon: fire_advertising_id
  • Microsoft: microsoft_advertising_id
  • Roku: roku_advertising_id
App IDapplication_idSystem-assigned ID to a customer application.
Browser IDbrowser_idID provided via a browser cookie.
Email AddressemailPersonal, work, or other types of email address.
Identifier value returned will be validated.
Phone NumberphonePersonal, work, cell, or other types of phone numbers.
Identifier value returned will be validated.
Service IDservice_idSystem-assigned ID for a data subject record.
Social Media IDsocial_media_idID provided via a social media profile.

Subcategory keys:
  • Twitter: twitter_id
  • Facebook: facebook_id
  • Intercom: intercom_id
  • Smooch: smooch_id
User IDuser_idCustom customer assigned ID for a data subject record.

Files​

A list of objects containing key-value pairs of file names and file contents to upload.

NameDescription
files[]object(File)
An array of File objects.

File​

An individual file and its contents.

NameDescription
<file_name>string
The file to upload. Files must be converted to printable ASCII characters (Base64).

FileRefs​

A list of file paths in your cloud storage to sync.

NameDescription
file_refs[]string
An array of file paths in your cloud storage.

The file paths must be located in the bucket that is integrated with Cyera, and must use the following file path format:
api_integration_files_sync/{privacy_request_id}/{integration_id}/{file}

Enums​

RequestType​

The action to perform.

EnumDescription
health_checkstring
The request is for a health check.
accessstring
The request is for access.
deletionstring
The request is for deletion.
opt_outstring
The request is for opt-out.
readiness_checkstring
The request is for a readiness check.
identifiersstring
The request is for identifier retrieval.

Topic​

The request notification type.

EnumDescription
privacy_request:createstring
The request is to create a new privacy request.
privacy_request:reminderstring
The request is a reminder of an incomplete privacy request.
opt_out:createstring
The request is to create a new opt-out request.
opt_out:reminderstring
The request is a reminder of an incomplete opt-out request.
identifiers:createstring
The request is to retrieve identifiers.
identifiers:reminderstring
The request is a reminder of an incomplete identifier retrieval.

Status​

The status that is set for an integration on a privacy request.

Access and Deletion Requests​
EnumDescription
completedstring
The integration for the request should be marked as completed.
ignoredstring
The integration for the request should be marked as ignored.
Opt-Out Requests​
EnumDescription
completestring
The integration for the request should be marked as complete.
errorstring
The integration for the request should be marked as error.
Identifier Retrieval Requests​
EnumDescription
completedstring
Identifier retrieval is complete. This is the only accepted value.

 

Need help?
If you have any questions, please reach out to your dedicated Customer Success Engineer or contact us at support@cyera.io.

Disclaimer: The information contained in this message does not constitute as legal advice. We would advise seeking professional counsel before acting on or interpreting any material.