Reciba notificaciones de webhook para sus listas de público

En esta guía, se explica cómo usar los webhooks para recibir notificaciones asíncronas sobre el estado de tus solicitudes de exportación de públicos. Esta función solo está disponible en la versión v1alpha de la API de datos.

Las notificaciones de webhook son una función avanzada de la API de datos de Google Analytics. Para obtener una introducción a la función de exportación de públicos, consulta Cómo crear una exportación de públicos.

Sin webhooks, deberás sondear la API de forma periódica para determinar cuándo se completa una solicitud.

Crea una aplicación de webhook de ejemplo con Cloud Run

Para crear una aplicación de webhook de muestra con Google Cloud, sigue el instructivo Guía de inicio rápido: Implementa un servicio de muestra en Cloud Run.

Para que el servicio de ejemplo escuche las solicitudes de notificación de webhook POST, reemplaza el archivo index.js del instructivo de la guía de inicio rápido por el siguiente 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 notificación de webhook entrante que se envía como una solicitud POST, este código imprime el cuerpo JSON de la notificación del webhook y un valor de token de canal, y muestra el código HTTP 200 para indicar que la operación se realizó correctamente.

Cuando llegues al final de la guía de inicio rápido de Cloud Run y hayas implementado la aplicación de webhook con el comando gcloud run deploy, guarda la URL en la que se implementó tu servicio.

La URL del servicio se muestra en la consola, por ejemplo:

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

Este es el URI de notificación del servidor en el que tu aplicación escucha las notificaciones de webhook de Google Analytics.

Crea una lista de público y activa las notificaciones de webhook

Para solicitar notificaciones de webhook, especifica los siguientes valores en el objeto webhookNotification:

  • El URI de notificación del servidor que contiene la dirección web que recibirá las notificaciones de webhook.

  • (Opcional) Es una cadena arbitraria channelToken para evitar que se falsifique el mensaje. Especifica el channelToken en el encabezado HTTP X-Goog-Channel-Token de la solicitud POST del webhook.

A continuación, se muestra una solicitud de ejemplo con webhooks:

Solicitud 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"
    }
  ]
}

La respuesta del método audienceLists.create contiene webhookNotification, que confirma que el webhook especificado respondió correctamente en menos de 5 segundos.

Esta es una respuesta de ejemplo:

Respuesta 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"
    }
  }
}

Si un webhook no responde o si proporcionas una URL de servicio incorrecta, se mostrará un mensaje de error.

Este es un ejemplo de error que podrías recibir:

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

Cómo procesar notificaciones de webhook

La solicitud POST a un servicio de webhook contiene una versión JSON del recurso de operación de larga duración en el cuerpo y un campo sentTimestamp. La marca de tiempo enviada especifica la época de Unix en microsegundos en la que se envió la solicitud. Puedes usar esta marca de tiempo para identificar las notificaciones reproducidas.

Se envían una o dos solicitudes POST al webhook durante la creación de una lista de público:

  1. La primera solicitud POST se envía de inmediato y muestra la lista de público creada recientemente en su estado CREATING. Si la primera solicitud al webhook falla, la operación audienceLists.create muestra un error y los detalles de la falla del webhook.
  2. La segunda solicitud POST se envía después de que se completa la creación de la lista de público. La creación se completa cuando la lista de público alcanza el estado ACTIVE o FAILED.

Este es un ejemplo de la primera notificación de una lista de público, en el 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"
      }
  }

Este es un ejemplo de la segunda notificación para una lista de público, en el 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"
      }
  }

La segunda notificación confirma que se creó la lista de público y que está lista para consultarse con el método audienceLists.query.

Para probar los webhooks después de llamar al método audienceLists.create, puedes inspeccionar los registros de tu aplicación de ejemplo de webhook de Cloud Run y ver el cuerpo JSON de cada notificación que envía Google Analytics.