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. SeeCommonEventObject.authorizationEventObject: User OAuth access tokens, user ID tokens, and system-authorized scopes. SeeAuthorizationEventObject.
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). SeeGmailEventObject. - 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). SeeDriveEventObject. - Chat: Event type (
ADDED_TO_SPACE,REMOVED_FROM_SPACE,MESSAGE,CARD_CLICKED), space metadata, user details, and payload data. SeeChatEventObject. - 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:
RenderActions: Renders new cards, navigates card stacks, or executes UI actions (for example,{"action": {"navigations": [...]}}or{"renderActions": ...}).SubmitFormResponse: Responds to a user form submit action with card render instructions and an optional state update indicator (for example,{"renderActions": {...}, "stateChanged": true}).GetAutocompletionResponse: Provides dynamic text suggestions for widget autocomplete fields (for example,{"autoComplete": {"items": [...]}}).DataActions: Performs document mutations or Chat space actions triggered by the callback (for example,{"hostAppDataAction": {...}}).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
- Request schema fragment: