Google Workspace add-ons endpoint interface


Service overview

When a user triggers an interaction in a supported host application (Gmail, Google Calendar, Google Drive, Google Chat, Google Docs, Google Sheets, Google Slides, or Workspace Studio), the host sends an HTTP POST event payload to your configured add-on callback URL (/*).

Your add-on endpoint must receive an EventObject request payload and return one of the five valid JSON response types documented in Response: HandleEventResponse.


Webhook endpoint contract

Method Endpoint path Request body Response body
POST /* (or configured callback path) EventObject One of 5 response types

Request: EventObject

An EventObject contains top-level metadata, common event fields, and host-application contextual details:

Common and authorization context

  • commonEventObject: User locale, host application enum (GMAIL, CALENDAR, DRIVE, CHAT, DOCS, SHEETS, SLIDES, WORKFLOW), user platform, timezone, widget form input values (formInputs), and custom parameters. See CommonEventObject.
  • authorizationEventObject: User OAuth access tokens, user ID tokens, and system-authorized scopes. See AuthorizationEventObject.

Host application event objects

Depending on which application invokes the callback, one of the following host objects is present:

  • Gmail: Message ID, thread ID, temporary access token, and message recipient lists (toRecipients, ccRecipients, bccRecipients). See GmailEventObject.
  • Calendar: Event ID, recurring event ID, calendar ID, organizer information, attendees, conference data, and entry points. See CalendarEventObject.
  • Drive: Selected files or folders (selectedItems) and current cursor item metadata (activeCursorItem). See DriveEventObject.
  • Chat: Event type (ADDED_TO_SPACE, REMOVED_FROM_SPACE, MESSAGE, CARD_CLICKED), space metadata, user details, and payload data. See ChatEventObject.
  • Workspace Studio: Action invocations, trigger lifecycle events, element configurations, resource retrievals, and variable data maps. See WorkflowEventObject.
  • Docs: Document ID, title, file-scope permission flag, and matched URL pattern. See DocsEventObject.
  • Sheets: Spreadsheet ID, title, file-scope permission flag, and matched URL pattern. See SheetsEventObject.
  • Slides: Presentation ID, title, file-scope permission flag, and matched URL pattern. See SlidesEventObject.

Response: HandleEventResponse

The HTTP response returned by your webhook endpoint is an untagged root JSON object that must be an instance of one of the following five response types:

  1. RenderActions: Renders new cards, navigates card stacks, or executes UI actions (for example, {"action": {"navigations": [...]}} or {"renderActions": ...}).
  2. SubmitFormResponse: Responds to a user form submit action with card render instructions and an optional state update indicator (for example, {"renderActions": {...}, "stateChanged": true}).
  3. GetAutocompletionResponse: Provides dynamic text suggestions for widget autocomplete fields (for example, {"autoComplete": {"items": [...]}}).
  4. DataActions: Performs document mutations or Chat space actions triggered by the callback (for example, {"hostAppDataAction": {...}}).
  5. AuthorizationError: Prompts the user to authorize external third-party credentials or requests additional Google OAuth scopes (for example, {"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).

Standalone OpenAPI 3.0 specification and JSON Schemas

To automatically generate server stubs, SDK client libraries, or payload validation schemas for your callback endpoint, consult the following specification files:

  • OpenAPI 3.0.3 specification: addon_callback_openapi.json
  • JSON Schema definitions: endpoint_interface.schema.json
    • Request schema fragment: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject
    • Response schema fragment: endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse