Documentação dos Webhooks da AdOpt

Os webhooks da AdOpt permitem que você receba notificações em tempo real sobre eventos relacionados à sua conta e aos fluxos de consentimento e solicitações de direitos dos titulares (DSAR).

Ao configurar um webhook, a AdOpt envia uma requisição HTTP para o endpoint informado sempre que um evento compatível ocorrer. Isso permite integrar a AdOpt a sistemas externos e automatizar processos como atualização de dados, gestão de consentimentos e atendimento a solicitações de exclusão de dados.

1. Criando um Webhook

Para criar um webhook, siga os seguintes passos:

Acesse a aba "Webhooks" dentro do seu dashboard da AdOpt.
Procure pela opção de criar um novo webhook.
Informe os dados necessários, como:
- Endpoint de destino (URL);
- Descrição;
- **Eventos** que o webhook deve receber (ao menos um).
Salve a configuração.

Após a criação, o webhook estará pronto para receber as notificações enviadas pela AdOpt.

⚠️ Importante: Verifique se o endpoint informado está preparado para receber requisições HTTP POST e processar um corpo no formato JSON.

⚠️ Importante: a AdOpt só envia eventos para webhooks que estejam habilitados e que tenham aquele evento selecionado no painel de webhooks da AdOpt. Se nenhum evento for marcado, ou se o webhook estiver desabilitado, nenhuma requisição é enviada.

2. Configurando a Assinatura

Cada webhook possui uma Secret Signing exclusiva.

Essa chave é utilizada para validar a autenticidade das requisições enviadas pela AdOpt por meio de uma assinatura HMAC.

A Secret Signing deve ser armazenada de forma segura no seu sistema e não deve ser exposta no código do lado do cliente ou compartilhada publicamente.

A requisição enviada pela AdOpt contém a assinatura e os dados relacionados ao evento.

Exemplo de estrutura:

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

A propriedade signature deve ser utilizada em conjunto com a sua Secret Signing para validar se a requisição foi realmente enviada pela AdOpt e se o conteúdo recebido corresponde ao conteúdo utilizado para gerar a assinatura.

A assinatura é um HMAC-SHA256 em hexadecimal, calculado apenas sobre o objeto data. O detalhamento está na seção 6.

3. Recebendo Eventos

Quando um evento ocorrer, a AdOpt enviará uma requisição HTTP POST para o endpoint configurado no webhook.

O corpo da requisição será enviado no formato JSON.

De forma geral, a estrutura possui duas partes principais:

data: contém as informações relacionadas ao evento;
signature: contém a assinatura HMAC utilizada para validar a requisição.

Exemplo:

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

O campo type identifica qual evento foi recebido.

Sua aplicação deve utilizar esse campo para determinar qual processo deve ser executado.

Resposta esperada

Responda com um status HTTP 2xx assim que receber o evento. O tempo limite da requisição é de 30 segundos.

⚠️ Importante: a AdOpt não reenvia automaticamente um webhook que falhou. Se o seu endpoint responder com erro, expirar ou estiver indisponível, o evento não é reenviado por conta própria. Todas as tentativas ficam registradas no dashboard, de onde é possível reenviar um evento manualmente.

4. Eventos disponíveis

Os webhooks da AdOpt podem ser utilizados para receber notificações relacionadas a diferentes eventos da plataforma.

O tipo do evento é informado no campo:

```text
data.type
```

Os eventos disponíveis são:

Evento	Descrição
`dataExistence`	Solicitação de confirmação da existência de dados
`dataAccess`	Solicitação de acesso aos dados
`dataCorrection`	Solicitação de correção de dados
`dataSharingInformation`	Solicitação de informação sobre compartilhamento de dados
`dataAnonymization`	Solicitação de anonimização de dados
`dataRemoval`	Solicitação de exclusão de dados
`dataPortability`	Solicitação de portabilidade de dados
`consentRevocation`	Revogação de consentimento
`consentRefusal`	Recusa de consentimento
`automatedDecisionReview`	Solicitação de revisão de decisão automatizada
`doNotSellData`	Solicitação de não venda de dados

4.1 Origem dos eventos

Os eventos podem ser originados por dois fluxos diferentes da AdOpt, e o payload não é idêntico entre eles:

Página de opt-out: gera apenas dataRemoval e dataExistence. O evento é enviado assim que a solicitação é registrada. É o único fluxo que envia o campo email.
Portal de Privacidade (pPágina de Requisições): gera todos os eventos da tabela acima. O evento é enviado somente após o titular confirmar a solicitação por e-mail. Não envia o campo email.

Verifique qual fluxo está ativo no seu Aviso antes de implementar a integração.

5. Evento `dataRemoval`

O evento `dataRemoval` é enviado quando uma solicitação de exclusão de dados é registrada pela AdOpt.

Esse evento foi desenvolvido para permitir que sistemas externos processem automaticamente as solicitações de exclusão de dados recebidas pela AdOpt.

O payload descrito nesta seção é o da **página de opt-out**, que é o fluxo que envia o campo `email`. No **Portal de Privacidade** o payload é o mesmo, porém **sem o campo `email`**, e o evento só é enviado depois que o titular confirma a solicitação por e-mail. Ver seção 4, "Origem dos eventos".

O evento `dataExistence` tem exatamente o mesmo formato de payload, mudando apenas o valor de `data.type`.

5.1 Payload

O payload do evento possui a seguinte estrutura:

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

5.2 Campos do evento

Campo	Tipo	Presença	Descrição
`data.type`	`string`	Sempre	Identifica o tipo do evento. Para solicitações de exclusão, o valor é `dataRemoval`.
`data.email`	`string`	Opcional	E-mail informado pelo titular durante a solicitação. Enviado apenas pela página de opt-out. Ver a próxima subseção.
`data.visitorId`	`string`	Sempre	Identificador do visitante na AdOpt.
`data.consentId`	`string`	Sempre	Identificador relacionado ao consentimento. É derivado de `websiteId` e `visitorId`, portanto se repete entre solicitações do mesmo visitante.
`data.websiteId`	`string`	Sempre	Identificador do website relacionado ao evento.
`data.disclaimerId`	`string`	Sempre	Identificador do aviso relacionado ao evento.
`data.device`	`string`	Opcional	Dispositivo utilizado na realização da solicitação. Valores possíveis: web ou mobile. A chave é omitida quando o dispositivo não é informado.
`data.disclaimer_main_version`	`number`	Sempre	Versão principal do disclaimer relacionada ao evento. O valor 0 indica que a versão não pôde ser determinada.
`signature`	`string`	Sempre	Assinatura HMAC utilizada para validar a autenticidade da requisição.

⚠️ Importante: campos marcados como opcionais são omitidos do JSON quando não possuem valor. A chave simplesmente não aparece no payload, não vem como null nem como string vazia.

5.3 Campo `email`

O campo email contém o endereço informado pelo titular durante o processo de solicitação de exclusão de dados.

Esse campo permite que sua aplicação identifique o titular diretamente nos sistemas externos utilizados pela sua organização, como:

CRM;
Plataformas de e-mail marketing;
Bancos de dados;
Sistemas internos;
Ferramentas de automação;
Outros sistemas que utilizem o endereço de e-mail como identificador.

Não é necessário realizar nenhuma configuração adicional para receber o campo email.

Ele é enviado automaticamente nos eventos dataRemoval e dataExistence originados pela página de opt-out, desde que o titular tenha informado um e-mail.

⚠️ Importante: em dataRemoval o e-mail é opcional. Se o titular não informar um e-mail, a chave `email` não aparece no payload, e sua aplicação precisa tratar essa ausência. Em dataExistence o e-mail é obrigatório e sempre estará presente.

⚠️ Importante: eventos originados pelo Portal de Privacidade não incluem o campo email. Ver seção 4.1, "Origem dos eventos".

5.4 Exemplo de uso

Ao receber uma solicitação:

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

Sua aplicação pode utilizar o valor de:

```text
data.email
```

para localizar os registros correspondentes ao titular e executar os procedimentos internos de exclusão ou anonimização de dados.

Por exemplo:

```text
Solicitação recebida
        ↓
Validar assinatura HMAC
        ↓
Verificar data.type = "dataRemoval"
        ↓
Obter data.email
        ↓
Localizar o titular nos sistemas internos
        ↓
Executar exclusão/anonimização
        ↓
Registrar o processamento da solicitação
```

⚠️ Importante: a implementação do processo de exclusão nos sistemas externos é de responsabilidade da aplicação que recebe o webhook. A AdOpt apenas notifica sua aplicação sobre a solicitação recebida.

6. Validando a Chamada

Para garantir a autenticidade das chamadas recebidas, recomendamos validar a assinatura HMAC antes de processar os dados do webhook.

A validação deve ser realizada utilizando a Secret Signing configurada para o webhook.

Passo 1 — Obtenha a Secret Signing

Acesse o dashboard da AdOpt e consulte a Secret Signing associada ao webhook.

Armazene essa chave de forma segura no seu servidor.

Passo 2 — Receba o payload

Sua aplicação receberá uma requisição POST contendo o corpo JSON enviado pela AdOpt.

A requisição terá a estrutura descrita na seção 3: um objeto data com os campos do evento e um campo signature no mesmo nível.

⚠️ Importante: preserve o corpo bruto da requisição. A assinatura é calculada sobre os bytes exatos do objeto data como ele foi serializado pela AdOpt. Se você fizer o parse do JSON e serializá-lo novamente, a ordem das chaves e o escaping de caracteres podem mudar, e a assinatura não vai corresponder.

Passo 3 — Calcule o HMAC

Calcule um HMAC-SHA256 usando a Secret Signing do webhook como chave e, como conteúdo, apenas o objeto data em JSON, exatamente como recebido. O campo signature não entra no cálculo.

O resultado deve ser representado em hexadecimal minúsculo:

```text
signature = HMAC_SHA256(secret_signing, json_bruto_do_objeto_data) em hexadecimal
```

Passo 4 — Compare as assinaturas

Compare a assinatura calculada pela sua aplicação com o valor recebido no campo:

```text
signature
```

Se as assinaturas forem equivalentes, a requisição pode ser considerada válida.

Caso a assinatura não corresponda, recomendamos rejeitar a requisição e não processar os dados recebidos.

⚠️ Importante: a validação deve ser realizada antes de executar qualquer ação relacionada ao evento, especialmente quando o webhook estiver sendo utilizado para processos de exclusão ou alteração de dados.

7. Boas práticas de segurança

Como os webhooks podem transportar informações relacionadas a titulares e solicitações de direitos, recomendamos adotar boas práticas de segurança ao implementar sua integração.

7.1 Proteja sua Secret Signing

Nunca exponha a Secret Signing no frontend, em repositórios públicos ou em logs acessíveis a terceiros.

7.2 Valide a assinatura

Sempre valide a assinatura HMAC antes de processar o evento.

7.4 Utilize HTTPS

O endpoint utilizado para receber os webhooks deve utilizar HTTPS para proteger os dados durante o transporte.

7.5 Evite registrar dados sensíveis desnecessariamente

Evite armazenar o payload completo do webhook em logs de aplicação quando isso não for necessário.

Em especial, tenha cuidado com o campo email, que pode ser utilizado para identificar diretamente um titular.

7.6 Implemente idempotência

A AdOpt não reenvia automaticamente eventos que falharam, mas um evento pode ser reenviado manualmente pelo dashboard. Sua aplicação deve considerar a possibilidade de receber uma mesma notificação mais de uma vez.

O payload não possui um identificador único de evento. Para deduplicar, utilize a combinação de data.type, data.visitorId e data.websiteId junto ao momento do recebimento, conforme as regras do seu sistema.

ℹ️ Info: o reenvio manual reenvia o payload exatamente como ele foi registrado no envio original.

7.7 Processe as solicitações de exclusão com segurança

Ao receber um evento dataRemoval, certifique-se de que os procedimentos de exclusão ou anonimização implementados em seus sistemas internos estejam de acordo com suas políticas de segurança, privacidade e requisitos legais aplicáveis.

8. Conclusão

Os webhooks da AdOpt permitem integrar eventos da plataforma aos seus próprios sistemas e automatizar processos relacionados a consentimento e direitos dos titulares.

Para solicitações de exclusão de dados, o evento dataRemoval fornece as informações necessárias para que sua aplicação identifique a solicitação e execute os procedimentos correspondentes.

Quando presente, o campo email permite utilizar diretamente o endereço informado pelo titular para localizar seus registros em sistemas externos, facilitando a automação dos processos de exclusão ou anonimização de dados.

Para uma integração segura, recomendamos:

Configurar um endpoint HTTPS para receber os webhooks;
Armazenar a Secret Signing de forma segura;
Validar a assinatura HMAC antes de processar os eventos;
Verificar o campo data.type para identificar o evento recebido;
Utilizar data.email para identificar o titular quando o evento for dataRemoval;
Tratar a ausência das chaves opcionais (`email` e `device`) no payload;
Implementar mecanismos de idempotência;
Processar as solicitações de exclusão de acordo com os requisitos de segurança, privacidade e legislação aplicável.

Com essas etapas, sua aplicação estará preparada para receber e processar os eventos enviados pela AdOpt de forma segura e automatizada.