Webhooks API: Register Endpoints for Real-Time Events

Register and manage webhook endpoints to receive real-time HTTP POST notifications when data changes or user events occur in your account.

Webhooks allow your application to react to events in your Google account the moment they happen, without the need for repeated polling. When a relevant event occurs — such as a new data object being created or a user being invited — Google sends an HTTP POST request to a URL of your choosing, containing a JSON payload with full details about the event. You can register multiple webhook endpoints, each subscribed to a different set of events, giving you fine-grained control over which parts of your system are notified about which activity.

Supported Events

The following events can be subscribed to when you register a webhook endpoint. Each event name corresponds to a specific action taken within your account.

Event	Description
data.created	Fired when a new data object is successfully created in your account.
data.updated	Fired when an existing data object’s title, content, tags, or metadata is modified.
data.deleted	Fired when a data object is permanently deleted from your account.
user.created	Fired when a new user is invited to your account via POST /v1/users.

Payload Structure

All events share a common JSON envelope, with a top-level event field identifying the event type and a data field containing the relevant object. Your endpoint will always receive a Content-Type: application/json header alongside the payload body.

{
  "event": "data.created",
  "timestamp": "2024-06-01T10:00:00Z",
  "account_id": "acc_xyz123",
  "data": {
    "id": "dat_abc123",
    "title": "New Report",
    "type": "document"
  }
}

---

POST /v1/webhooks

Register a new webhook endpoint that will receive event notifications. You can subscribe each endpoint to one or more of the supported event types. Optionally, you can provide a secret that Google will use to sign every payload, allowing your server to verify the request is authentic. This endpoint requires write scope and returns 201 Created on success.

Request Body

url · string · required

The publicly accessible HTTPS URL to which Google will send event payloads. The URL must respond with a 2xx status code within 10 seconds to be considered a successful delivery. HTTP URLs are not accepted — your endpoint must use HTTPS.

events · array · required

An array of event name strings to subscribe this endpoint to. At least one event name is required. Valid values are data.created, data.updated, data.deleted, and user.created. Pass ["*"] to subscribe to all current and future events.

secret · string

An optional secret string used to generate an HMAC-SHA256 signature for each outgoing payload. When provided, Google includes a X-Google-Signature header on every request so your server can verify the payload’s authenticity. See Verifying Webhook Signatures below.

Example Request

cURL

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",
    "events": ["data.created", "data.updated"],
    "secret": "your_signing_secret"
  }'

Example Response

{
  "data": {
    "id": "wh_abc123",
    "url": "https://yourapp.com/webhooks",
    "events": ["data.created", "data.updated"],
    "status": "active",
    "created_at": "2024-06-01T10:00:00Z"
  }
}

Response Fields

id · string

The unique identifier for the newly registered webhook, prefixed with wh_.

url · string

The HTTPS URL that will receive event payloads.

events · array

The list of event names this endpoint is subscribed to, as provided in the request body.

status · string

The current status of the webhook. Newly registered webhooks start as active.

created_at · string

The ISO 8601 timestamp at which the webhook was registered, in UTC.

---

GET /v1/webhooks

Retrieve a list of all webhook endpoints currently registered to your account, including their subscribed events and status.

Example Request

cURL

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

Example Response

{
  "data": {
    "webhooks": [
      {
        "id": "wh_abc123",
        "url": "https://yourapp.com/webhooks",
        "events": ["data.created", "data.updated"],
        "status": "active",
        "created_at": "2024-06-01T10:00:00Z"
      }
    ],
    "total": 1
  }
}

Response Fields

webhooks · array

An array of registered webhook endpoint objects.

Show webhooks[]

id · string

The unique identifier for the webhook, prefixed with wh_.

url · string

The HTTPS URL that receives event payloads.

events · array

The list of event names this endpoint is subscribed to.

status · string

The current status of the webhook. Either active or disabled. An endpoint may be automatically disabled after repeated delivery failures.

created_at · string

The ISO 8601 timestamp at which the webhook was registered, in UTC.

total · integer

The total number of webhook endpoints registered to your account.

---

DELETE /v1/webhooks/

Remove a registered webhook endpoint from your account. Once deleted, no further event payloads will be sent to that URL. This endpoint returns 204 No Content on success with an empty response body.

Path Parameters

id · string · required

The unique identifier of the webhook to remove, for example wh_abc123. You can retrieve this from the GET /v1/webhooks listing.

Example Request

cURL

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

A successful response returns HTTP 204 No Content with no body.

Response Fields

This endpoint returns no response body. A 204 No Content status code confirms the webhook endpoint was successfully removed.

---

Verifying Webhook Signatures

If you provided a secret when registering your webhook, Google signs the raw JSON payload body using HMAC-SHA256 and includes the resulting hex digest in the X-Google-Signature request header. You should always verify this signature before processing the event to confirm the request genuinely originated from Google and was not tampered with in transit.

Python

import hmac
import hashlib

def verify_signature(secret: str, payload_bytes: bytes, received_sig: str) -> bool:
    expected_sig = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected_sig, received_sig)

# Usage in your request handler:
# verify_signature(SECRET, request.body, request.headers['X-Google-Signature'])

Always compare signatures using a timing-safe equality function (such as hmac.compare_digest in Python or crypto.timingSafeEqual in Node.js) to prevent timing-based attacks.

Respond to incoming webhook requests with an HTTP 200 status code as quickly as possible — ideally within 2–3 seconds — and handle any heavy processing asynchronously in a background job or queue. If your endpoint takes too long to respond, the delivery will be treated as a failure and retried, potentially causing duplicate processing on your side.

If your endpoint does not return a 2xx response within 10 seconds, Google treats the delivery as failed and retries it up to 5 times using exponential backoff. Retry intervals are approximately 1 min, 5 min, 30 min, 2 hours, and 8 hours. After 5 failed attempts, no further retries are made and the webhook endpoint may be automatically disabled.