Webhooks API: Register and Manage Real-Time Event Listeners

Webhooks let your external systems react to activity in your Google workspace the moment it happens, without polling. When an event occurs — a record is created, a user is removed, an integration goes live — Google sends an HTTP POST request with a structured JSON payload to the URL you register. This makes it straightforward to build automation pipelines, audit logs, or live dashboards that stay in sync with your workspace in real time.

Available Events

The following events can trigger webhook deliveries to your registered endpoints.

Event	Triggered When
`record.created`	A new data record is created
`record.updated`	A data record is modified
`record.deleted`	A data record is deleted
`user.invited`	A user is invited to the workspace
`user.removed`	A user is removed
`integration.connected`	An integration is connected
`integration.disconnected`	An integration is removed

Webhook Payload

Every webhook delivery is a POST request to your registered URL with a Content-Type: application/json header and a consistent JSON body structure. The data object reflects the resource that triggered the event.

Example Payload

{
  "event": "record.created",
  "timestamp": "2024-03-10T14:22:00Z",
  "workspace_id": "ws_xyz789",
  "data": {
    "id": "rec_abc123",
    "name": "New Record",
    "type": "document",
    "created_by": "usr_abc123"
  }
}

Payload Fields

string

The event type that triggered this delivery (e.g., record.created).

string

ISO 8601 timestamp of when the event occurred in the workspace.

string

The unique identifier of the workspace where the event took place.

object

The resource object associated with the event. The shape of this object varies by event type — record events include record fields, user events include user fields, and so on.

Google expects your endpoint to respond with an HTTP 2xx status code within 5 seconds. If the delivery times out or receives a non-2xx response, it will be retried up to three times with exponential backoff.

Register Webhook

Register a new endpoint URL to start receiving event notifications for your workspace. POST https://api.google.com/v1/webhooks

Body Parameters

string

required

The publicly accessible HTTPS URL that Google should send event payloads to. Must begin with https://.

array

required

An array of event type strings to subscribe to. Use ["*"] to subscribe to all events. See the Available Events table for valid values.

string

An optional secret string used to generate an HMAC-SHA256 signature for each delivery. When provided, Google includes an X-Google-Signature header with every request so you can verify authenticity. See Verifying Webhook Signatures for implementation details.

Example Request

curl -X POST "https://api.google.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/google",
    "events": ["record.created", "record.updated", "user.invited"],
    "secret": "your_signing_secret"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://yourapp.com/webhooks/google",
    "events": ["record.created", "record.updated", "user.invited"],
    "status": "active",
    "created_at": "2024-06-01T09:00:00Z"
  }
}

List Webhooks

Retrieve all webhook registrations for your workspace. GET https://api.google.com/v1/webhooks

Example Request

curl -X GET "https://api.google.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "wh_abc123",
      "url": "https://yourapp.com/webhooks/google",
      "events": ["record.created", "record.updated", "user.invited"],
      "status": "active",
      "created_at": "2024-06-01T09:00:00Z"
    },
    {
      "id": "wh_def456",
      "url": "https://yourapp.com/webhooks/audit",
      "events": ["user.removed", "integration.disconnected"],
      "status": "active",
      "created_at": "2024-06-02T11:30:00Z"
    }
  ],
  "meta": { "total": 2 }
}

Delete Webhook

Remove a registered webhook. Google will immediately stop delivering events to the associated URL. DELETE https://api.google.com/v1/webhooks/:id

Path Parameters

string

required

The unique identifier of the webhook to delete (e.g., wh_abc123).

Example Request

curl -X DELETE "https://api.google.com/v1/webhooks/wh_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful deletion returns HTTP 204 No Content with an empty body.

Verifying Webhook Signatures

When you register a webhook with a secret, Google includes an X-Google-Signature header with every request. The value is a SHA-256 HMAC of the raw request body, prefixed with sha256=. Verifying this signature ensures the payload genuinely came from Google and has not been tampered with.

Verification Example (Node.js)

const crypto = require('crypto');
const express = require('express');
const app = express();

// Use the raw body buffer for signature verification — do NOT use express.json()
// middleware before this route, as JSON parsing discards whitespace and may
// produce a different byte sequence than the original payload.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-google-signature'];
  const rawBody = req.body; // Buffer containing the raw request bytes

  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  const expectedSig = Buffer.from(`sha256=${expected}`);
  const receivedSig = Buffer.from(sig || '');

  // Use timingSafeEqual to prevent timing attacks
  if (
    expectedSig.length !== receivedSig.length ||
    !crypto.timingSafeEqual(expectedSig, receivedSig)
  ) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  // Process the event
  console.log('Verified event:', event.event);
  res.status(200).send('OK');
});

Always compute the HMAC over the raw request body bytes — not a re-serialized JSON object. Parsing and re-stringifying the payload can change whitespace and key ordering, producing a different byte sequence and causing signature validation to fail. Use express.raw() (or equivalent) to capture the original bytes before any JSON parsing occurs.

While developing locally, use a tunneling tool like ngrok to expose your local server to the internet and receive live webhook deliveries. Run ngrok http 3000 to get a public HTTPS URL, then register that URL as your webhook endpoint. This lets you iterate on your handler without deploying to a staging environment.

Error Reference

400 Bad Request

The request body is missing required fields (url or events), the URL is not a valid HTTPS address, or the events array contains unrecognized event types.

401 Unauthorized

Your API key is missing or invalid. Include a valid Bearer token in the Authorization header.

404 Not Found

No webhook exists with the specified id. Use the List Webhooks endpoint to confirm the correct identifier.

422 Unprocessable Entity

The request is syntactically valid but the provided url is unreachable or returns non-2xx responses during validation.

429 Too Many Requests

You have exceeded the webhook registration limit for your plan. Review your existing webhooks and remove any that are no longer needed.

Overview

Endpoints

Webhooks API: Register and Manage Real-Time Event Listeners

Available Events

Webhook Payload

Example Payload

Payload Fields

Register Webhook

Body Parameters

Example Request

Example Response

List Webhooks

Example Request

Example Response

Delete Webhook

Path Parameters

Example Request

Verifying Webhook Signatures

Verification Example (Node.js)

Error Reference

​Available Events

​Webhook Payload

​Example Payload

​Payload Fields

​Register Webhook

​Body Parameters

​Example Request

​Example Response

​List Webhooks

​Example Request

​Example Response

​Delete Webhook

​Path Parameters

​Example Request

​Verifying Webhook Signatures

​Verification Example (Node.js)

​Error Reference

Available Events

Webhook Payload

Example Payload

Payload Fields

Register Webhook

Body Parameters

Example Request

Example Response

List Webhooks

Example Request

Example Response

Delete Webhook

Path Parameters

Example Request

Verifying Webhook Signatures

Verification Example (Node.js)

Error Reference