This guide explains how to use webhooks to receive asynchronous notifications for the status of your audience export requests. This feature is available only in the v1alpha version of the Data API.
Webhook notifications are an advanced feature of the Google Analytics Data API. For an introduction to the audience export feature, see create an audience export.
Without webhooks, you'll need to periodically poll the API to determine when a request is complete.
Create a sample webhook application using Cloud Run
You can create a sample webhook application using Google Cloud by following the tutorial Quickstart: Deploy a sample service to Cloud Run.
In order for the sample service to listen to POST webhook notification requests,
replace the index.js
file from the quickstart tutorial with the following
code:
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}`);
});
For every incoming webhook notification sent as a POST request, this code prints
out the webhook notification JSON body and a channel token value, and
returns the HTTP code 200
to indicate successful operation.
Once you've reached the end of the Cloud Run quickstart tutorial and deployed
the webhook application using the gcloud run deploy
command, save
the URL where your service is deployed.
The service URL is displayed in the console, for example:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
This is the server notification URI where your application listens to webhook notifications from Google Analytics.
Create an audience list and turn on webhook notifications
To request webhook notifications, specify the following values in the webhookNotification
object:
The server notification URI containing the web address that will receive webhook notifications.
(Optional) An arbitrary string
channelToken
to guard against the message being spoofed. Specify thechannelToken
in theX-Goog-Channel-Token
HTTP header of the webhook POST request.
Here's a sample request using webhooks:
HTTP Request
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"
}
]
}
The response from the audienceLists.create
method contains the
webhookNotification
, which confirms that the specified webhook successfully
responded in under 5 seconds.
Here's a sample response:
HTTP Response
{
"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"
}
}
}
If a webhook fails to respond, or if you provide an incorrect service URL, an error message is returned instead.
Here's an example error you might receive:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
Process webhook notifications
The POST request to a webhook service contains both a JSON version of the
long running operation resource
in the body, and a sentTimestamp
field. The sent timestamp specifies
the Unix epoch time in microseconds that the request was sent. You can use this
timestamp to identify replayed notifications.
Either one or two POST requests are sent to the webhook during an audience list creation:
- The first POST request is sent immediately, showing the newly created
audience list in its
CREATING
state. If the first request to the webhook fails, theaudienceLists.create
operation returns an error and the webhook failure details. - The second POST request is sent after the audience list completes
creation. Creation is complete when the audience list reaches either
the
ACTIVE
orFAILED
state.
Here's an example of the first notification for an audience list, in the
CREATING
state:
{
"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"
}
}
Here's an example of the second notification for an audience list, in the
ACTIVE
state:
{
"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"
}
}
The second notification confirms that the audience list has been created and is
ready to be queried using the audienceLists.query
method.
To test webhooks after calling the audienceLists.create
method, you can
inspect the logs
of your sample Cloud Run webhook application, and see the JSON body of every
notification sent by Google Analytics.