AdOpt Webhooks Documentation

AdOpt webhooks allow you to receive real-time notifications about events related to your account and consent flows and data subject rights requests (DSAR).

When configuring a webhook, AdOpt sends an HTTP request to the specified endpoint whenever a compatible event occurs. This allows you to integrate AdOpt with external systems and automate processes such as data updates, consent management, and handling data deletion requests.

1. Creating a Webhook

To create a webhook, follow these steps:

Go to the "Webhooks" tab within your AdOpt dashboard.
Look for the option to create a new webhook.
Enter the required information, such as:
- Destination endpoint (URL);
- Description;
- Events that the webhook should receive (at least one).
Save the configuration.

After creation, the webhook will be ready to receive notifications sent by AdOpt.

⚠️ Important: Make sure that the specified endpoint is prepared to receive HTTP POST requests and process a JSON body.

⚠️ Important: AdOpt only sends events to webhooks that are enabled and have that event selected in the AdOpt webhook panel. If no event is selected, or if the webhook is disabled, no request will be sent.

2. Configuring the Signature

Each webhook has a unique Secret Signing.

This key is used to validate the authenticity of requests sent by AdOpt through an HMAC signature.

The Secret Signing must be stored securely in your system and must not be exposed in client-side code or shared publicly.

The request sent by AdOpt contains the signature and the data related to the event.

Example structure:

{
  "data": {
    "...": "..."
  },
  "signature": "..."
}

The signature property must be used together with your Secret Signing to validate whether the request was actually sent by AdOpt and whether the received content corresponds to the content used to generate the signature.

The signature is an HMAC-SHA256 in hexadecimal, calculated only over the data object. Details are provided in Section 6.

3. Receiving Events

When an event occurs, AdOpt sends an HTTP POST request to the endpoint configured in the webhook.

The request body is sent in JSON format.

In general, the structure has two main parts:

data: contains information related to the event;
signature: contains the HMAC signature used to validate the request.

Example:

{
  "data": {
    "disclaimerId": "...",
    "visitorId": "...",
    "consentId": "...",
    "websiteId": "...",
    "device": "web",
    "disclaimer_main_version": 1,
    "email": "usuario@exemplo.com",
    "type": "dataRemoval"
  },
  "signature": "..."
}

The type field identifies which event was received.

Your application should use this field to determine which process should be executed.

3.1 Expected Response

Respond with an HTTP 2xx status as soon as the event is received. The request timeout is 30 seconds.

⚠️ Important: AdOpt does not automatically resend a webhook that failed. If your endpoint returns an error, times out, or is unavailable, the event is not resent automatically. All attempts are recorded in the dashboard, where you can manually resend an event.

4. Available Events

AdOpt webhooks can be used to receive notifications related to different events on the platform.

The event type is provided in the field:

data.type

The available events are:

Event	Description
`dataExistence`	Request to confirm the existence of data
`dataAccess`	Request to access data
`dataCorrection`	Request to correct data
`dataSharingInformation`	Request for information about data sharing
`dataAnonymization`	Request to anonymize data
`dataRemoval`	Request to delete data
`dataPortability`	Request for data portability
`consentRevocation`	Consent revocation
`consentRefusal`	Consent refusal
`automatedDecisionReview`	Request for review of an automated decision
`doNotSellData`	Request not to sell data

4.1 Event Sources

Events can originate from two different AdOpt flows, and the payload is not identical between them:

Opt-out page: generates only dataRemoval and dataExistence. The event is sent as soon as the request is registered. This is the only flow that sends the email field.
Privacy Portal (Requests page): generates all events listed in the table above. The event is sent only after the data subject confirms the request by email. It does not send the email field.

Check which flow is active in your Notice before implementing the integration.

5. `dataRemoval` Event

The dataRemoval event is sent when a data deletion request is registered by AdOpt.

This event is designed to allow external systems to automatically process data deletion requests received by AdOpt.

The payload described in this section is for the opt-out page, which is the flow that sends the email field. In the Privacy Portal, the payload is the same, but without the email field, and the event is only sent after the data subject confirms the request by email. See Section 4, "Event Sources."

The dataExistence event has exactly the same payload format, with only the value of data.type changing.

5.1 Payload

The event payload has the following structure:

{
  "data": {
    "disclaimerId": "...",
    "visitorId": "...",
    "consentId": "...",
    "websiteId": "...",
    "device": "web",
    "disclaimer_main_version": 1,
    "email": "usuario@exemplo.com",
    "type": "dataRemoval"
  },
  "signature": "..."
}

5.2 Event Fields

Field	Type	Presence	Description
`data.type`	`string`	Always	Identifies the type of event. For deletion requests, the value is `dataRemoval`.
`data.email`	`string`	Optional	Email address provided by the data subject during the request. Sent only by the opt-out page. See the next subsection.
`data.visitorId`	`string`	Always	Visitor identifier in AdOpt.
`data.consentId`	`string`	Always	Identifier related to consent. It is derived from `websiteId` and `visitorId`, and therefore repeats across requests from the same visitor.
`data.websiteId`	`string`	Always	Identifier of the website related to the event.
`data.disclaimerId`	`string`	Always	Identifier of the notice related to the event.
`data.device`	`string`	Optional	Device used to submit the request. Possible values: `web` or `mobile`. The key is omitted when the device is not provided.
`data.disclaimer_main_version`	`number`	Always	Main version of the disclaimer related to the event. A value of `0` indicates that the version could not be determined.
`signature`	`string`	Always	HMAC signature used to validate the authenticity of the request.

⚠️ Important: Fields marked as optional are omitted from the JSON when they have no value. The key simply does not appear in the payload; it is not sent as null or as an empty string.

5.3 `email` Field

The email field contains the email address provided by the data subject during the data deletion request process.

This field allows your application to directly identify the data subject in the external systems used by your organization, such as:

CRM;
Email marketing platforms;
Databases;
Internal systems;
Automation tools;
Other systems that use the email address as an identifier.

No additional configuration is required to receive the email field.

It is automatically sent in dataRemoval and dataExistence events originating from the opt-out page, provided that the data subject has provided an email address.

⚠️ Important: In dataRemoval, the email is optional. If the data subject does not provide an email address, the email key does not appear in the payload, and your application must handle its absence. In dataExistence, the email is mandatory and will always be present.

⚠️ Important: Events originating from the Privacy Portal do not include the email field. See Section 4.1, "Event Sources."

5.4 Usage Example

When receiving a request:

{
  "data": {
    "disclaimerId": "disclaimer123",
    "visitorId": "abc123",
    "consentId": "def456",
    "websiteId": "website789",
    "device": "web",
    "disclaimer_main_version": 1,
    "email": "maria@exemplo.com",
    "type": "dataRemoval"
  },
  "signature": "..."
}

Your application can use the value of:

data.email

to locate the corresponding records for the data subject and execute the internal data deletion or anonymization procedures.

For example:

Request received
        ↓
Validate HMAC signature
        ↓
Check data.type = "dataRemoval"
        ↓
Get data.email
        ↓
Locate the data subject in internal systems
        ↓
Execute deletion/anonymization
        ↓
Log the request processing

⚠️ Important: The implementation of the deletion process in external systems is the responsibility of the application receiving the webhook. AdOpt only notifies your application about the request received.

6. Validating the Request

To ensure the authenticity of received requests, we recommend validating the HMAC signature before processing webhook data.

Validation must be performed using the Secret Signing configured for the webhook.

Step 1 — Obtain the Secret Signing

Access the AdOpt dashboard and retrieve the Secret Signing associated with the webhook.

Store this key securely on your server.

Step 2 — Receive the Payload

Your application will receive a POST request containing the JSON body sent by AdOpt.

The request will have the structure described in Section 3: a data object containing the event fields and a signature field at the same level.

⚠️ Important: Preserve the raw request body. The signature is calculated over the exact bytes of the data object as serialized by AdOpt. If you parse the JSON and serialize it again, the key order and character escaping may change, and the signature will not match.

Step 3 — Calculate the HMAC

Calculate an HMAC-SHA256 using the webhook's Secret Signing as the key and, as the content, only the data object in JSON, exactly as received. The signature field is not included in the calculation.

The result must be represented in lowercase hexadecimal:

signature = HMAC_SHA256(secret_signing, raw_json_of_data_object) in hexadecimal

Step 4 — Compare the Signatures

Compare the signature calculated by your application with the value received in the:

signature

field.

If the signatures match, the request can be considered valid.

If the signature does not match, we recommend rejecting the request and not processing the received data.

⚠️ Important: Validation must be performed before executing any action related to the event, especially when the webhook is being used for data deletion or modification processes.

7. Security Best Practices

Because webhooks may carry information related to data subjects and data subject rights requests, we recommend adopting security best practices when implementing your integration.

7.1 Protect Your Secret Signing

Never expose the Secret Signing in frontend code, public repositories, or logs accessible to third parties.

7.2 Validate the Signature

Always validate the HMAC signature before processing the event.

7.4 Use HTTPS

The endpoint used to receive webhooks must use HTTPS to protect data during transmission.

7.5 Avoid Logging Sensitive Data Unnecessarily

Avoid storing the complete webhook payload in application logs when this is not necessary.

In particular, be careful with the email field, which can be used to directly identify a data subject.

7.6 Implement Idempotency

AdOpt does not automatically resend events that have failed, but an event can be manually resent from the dashboard. Your application should therefore account for the possibility of receiving the same notification more than once.

The payload does not contain a unique event identifier. For deduplication, use the combination of data.type, data.visitorId, and data.websiteId, together with the time of receipt, according to your system's rules.

ℹ️ Info: A manual resend resends the payload exactly as it was recorded in the original delivery.

7.7 Process Data Deletion Requests Securely

When receiving a dataRemoval event, make sure that the deletion or anonymization procedures implemented in your internal systems comply with your security and privacy policies and with applicable legal requirements.

8. Conclusion

AdOpt webhooks allow you to integrate platform events with your own systems and automate processes related to consent and data subject rights.

For data deletion requests, the dataRemoval event provides the information required for your application to identify the request and execute the corresponding procedures.

When present, the email field allows you to directly use the email address provided by the data subject to locate their records in external systems, facilitating the automation of data deletion or anonymization processes.

For a secure integration, we recommend:

Configure an HTTPS endpoint to receive webhooks;
Store the Secret Signing securely;
Validate the HMAC signature before processing events;
Check the data.type field to identify the received event;
Use data.email to identify the data subject when the event is dataRemoval;
Handle the absence of optional keys (email and device) in the payload;
Implement idempotency mechanisms;
Process deletion requests in accordance with applicable security, privacy, and legal requirements.

With these steps, your application will be prepared to securely and automatically receive and process events sent by AdOpt.