> [!NOTE]
> **Note:** This reference section documents the HTTP webhook endpoint interface implemented by your Google Workspace add-on server.

*** ** * ** ***

## 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`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#EventObject)
request payload and return one of the five valid JSON response types documented
in [Response: `HandleEventResponse`](https://developers.google.com/workspace/add-ons/reference/callback-contract.md.txt#response).

*** ** * ** ***

## Webhook endpoint contract

| Method | Endpoint path | Request body | Response body |
|---|---|---|---|
| `POST` | `/*` (or configured callback path) | [`EventObject`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#EventObject) | [One of 5 response types](https://developers.google.com/workspace/add-ons/reference/callback-contract.md.txt#response) |

*** ** * ** ***

## Request: `EventObject`

An [`EventObject`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#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`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#CommonEventObject).
- **`authorizationEventObject`** : User OAuth access tokens, user ID tokens, and system-authorized scopes. See [`AuthorizationEventObject`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#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`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#GmailEventObject).
- **Calendar** : Event ID, recurring event ID, calendar ID, organizer information, attendees, conference data, and entry points. See [`CalendarEventObject`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#CalendarEventObject).
- **Drive** : Selected files or folders (`selectedItems`) and current cursor item metadata (`activeCursorItem`). See [`DriveEventObject`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#DriveEventObject).
- **Chat** : Event type (`ADDED_TO_SPACE`, `REMOVED_FROM_SPACE`, `MESSAGE`, `CARD_CLICKED`), space metadata, user details, and payload data. See [`ChatEventObject`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#ChatEventObject).
- **Workspace Studio** : Action invocations, trigger lifecycle events, element configurations, resource retrievals, and variable data maps. See [`WorkflowEventObject`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#WorkflowEventObject).
- **Docs** : Document ID, title, file-scope permission flag, and matched URL pattern. See [`DocsEventObject`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#DocsEventObject).
- **Sheets** : Spreadsheet ID, title, file-scope permission flag, and matched URL pattern. See [`SheetsEventObject`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#SheetsEventObject).
- **Slides** : Presentation ID, title, file-scope permission flag, and matched URL pattern. See [`SlidesEventObject`](https://developers.google.com/workspace/add-ons/reference/event-object.md.txt#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`](https://developers.google.com/workspace/add-ons/reference/rpc/google.apps.card.v1.md.txt#google.apps.card.v1.RenderActions)** : Renders new cards, navigates card stacks, or executes UI actions (for example, `{"action": {"navigations": [...]}}` or `{"renderActions": ...}`).
2. **[`SubmitFormResponse`](https://developers.google.com/workspace/add-ons/reference/rpc/google.apps.card.v1.md.txt#google.apps.card.v1.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`](https://developers.google.com/workspace/add-ons/reference/rpc/google.apps.card.v1.md.txt#google.apps.card.v1.GetAutocompletionResponse)** : Provides dynamic text suggestions for widget autocomplete fields (for example, `{"autoComplete": {"items": [...]}}`).
4. **[`DataActions`](https://developers.google.com/workspace/add-ons/reference/rpc/google.apps.card.v1.md.txt#google.apps.card.v1.DataActions)** : Performs document mutations or Chat space actions triggered by the callback (for example, `{"hostAppDataAction": {...}}`).
5. **[`AuthorizationError`](https://developers.google.com/workspace/add-ons/reference/rpc/google.apps.card.v1.md.txt#google.apps.card.v1.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`](https://developers.google.com/static/workspace/add-ons/reference/schemas/addon_callback_openapi.json)
- **JSON Schema definitions** : [`endpoint_interface.schema.json`](https://developers.google.com/static/workspace/add-ons/reference/schemas/endpoint_interface.schema.json)
  - **Request schema fragment** : `endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject`
  - **Response schema fragment** : `endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse`