Receber notificações de webhook para suas listas de público-alvo

Neste guia, explicamos como usar webhooks para receber notificações assíncronas sobre o status das suas solicitações de exportação de público-alvo. Este recurso está disponível apenas na versão v1alpha da API Data.

As notificações de webhook são um recurso avançado da API Data do Google Analytics. Para uma introdução ao recurso de exportação de público-alvo, consulte Criar uma exportação de público-alvo.

Sem os webhooks, você precisará pesquisar periodicamente a API para determinar quando uma solicitação foi concluída.

Criar um aplicativo de webhook de amostra usando o Cloud Run

É possível criar um aplicativo de webhook de amostra usando o Google Cloud seguindo o tutorial Guia de início rápido: implantar um serviço de amostra no Cloud Run.

Para que o serviço de amostra detecte solicitações de notificação de webhook POST, substitua o arquivo index.js do tutorial de início rápido pelo seguinte código:

  import express from 'express';

  const app = express();
  app.use(express.json());

  app.post('/', (req, res) => {
    const channelToken = req.get('X-Goog-Channel-Token');
    const bodyJson = JSON.stringify(req.body);

    console.log(`channel token: ${channelToken}`);
    console.log(`notification body: ${bodyJson}`);

    res.sendStatus(200);
  });

  const port = parseInt(process.env.PORT) || 8080;
  app.listen(port, () => {
    console.log(`helloworld: listening on port ${port}`);
  });

Para cada notificação de webhook recebida enviada como uma solicitação POST, esse código imprime o corpo JSON de notificação de webhook e um valor de token de canal e retorna o código HTTP 200 para indicar a operação bem-sucedida.

Depois de chegar ao final do tutorial de início rápido do Cloud Run e implantar o aplicativo de webhook usando o comando gcloud run deploy, salve o URL em que o serviço será implantado.

O URL do serviço é exibido no console, por exemplo:

  Service URL: https://webhooks-test-abcdef-uc.a.run.app

Esse é o URI de notificação do servidor em que seu aplicativo detecta notificações webhook do Google Analytics.

Criar uma lista de público-alvo e ativar as notificações de webhook

Para solicitar notificações de webhook, especifique os seguintes valores no objeto webhookNotification:

  • O URI de notificação do servidor, contendo o endereço da Web que receberá notificações de webhook.

  • (Opcional) Uma string arbitrária channelToken para evitar spoofing de mensagem. Especifique o channelToken no cabeçalho HTTP X-Goog-Channel-Token da solicitação POST do webhook.

Veja um exemplo de solicitação que usa webhooks:

Solicitação HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
  "webhookNotification": {
    "uri": "https://webhooks-test-abcdef-uc.a.run.app",
    "channelToken": "123456"
  },
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

A resposta do método audienceLists.create contém webhookNotification, que confirma que o webhook especificado respondeu em menos de cinco segundos.

Veja um exemplo de resposta:

Resposta HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged": 51,
    "rowCount": 13956,
    "percentageCompleted": 100,
    "webhookNotification": {
      "uri": "https://webhooks-test-abcdef-uc.a.run.app",
      "channelToken": "123456"
    }
  }
}

Se o webhook não responder ou se você fornecer um URL de serviço incorreto, uma mensagem de erro será retornada.

Este é um exemplo de erro que você pode receber:

{
  "error": {
    "code": 400,
    "message": "Expected response code of 200 from webhook URI but instead
    '404' was received.",
    "status": "INVALID_ARGUMENT"
  }
}

Processar notificações webhook

A solicitação POST para um serviço de webhook contém uma versão JSON do recurso de operação de longa duração no corpo e um campo sentTimestamp. O carimbo de data/hora enviado especifica o horário da época Unix em microssegundos em que a solicitação foi enviada. Use esse carimbo de data/hora para identificar notificações repetidas.

Uma ou duas solicitações POST são enviadas ao webhook durante a criação de uma lista de público-alvo:

  1. A primeira solicitação POST é enviada imediatamente, mostrando a lista de público-alvo recém-criada no estado CREATING. Se a primeira solicitação para o webhook falhar, a operação audienceLists.create retornará um erro e os detalhes da falha do webhook.
  2. A segunda solicitação POST é enviada depois que a criação da lista de público-alvo é concluída. A criação é concluída quando a lista de público-alvo atinge o estado ACTIVE ou FAILED.

Confira um exemplo da primeira notificação de uma lista de público-alvo, no estado CREATING:

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"CREATING",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":0,
    "rowCount":0,
    "percentageCompleted":0,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

Confira um exemplo da segunda notificação de uma lista de público-alvo, no estado ACTIVE:

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":68,
    "rowCount":13956,
    "percentageCompleted":100,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

A segunda notificação confirma que a lista de público-alvo foi criada e está pronta para ser consultada usando o método audienceLists.query.

Para testar webhooks depois de chamar o método audienceLists.create, inspecione os registros do aplicativo de webhook de amostra do Cloud Run e veja o corpo JSON de cada notificação enviada pelo Google Analytics.