Visão geral do serviço
Quando um usuário aciona uma interação em um aplicativo host compatível
(Gmail, Google Agenda, Google Drive,
Google Chat, Documentos Google, Planilhas Google,
Apresentações Google ou Workspace Studio), o host envia um
payload de evento HTTP POST para o URL de callback do complemento configurado (/*).
O endpoint do complemento precisa receber um payload de solicitação EventObject e retornar um dos cinco tipos de resposta JSON válidos documentados em Resposta: HandleEventResponse.
Contrato de endpoint do webhook
| Método | Caminho do endpoint | Corpo da solicitação | Corpo da resposta |
|---|---|---|---|
POST |
/* (ou caminho de callback configurado) |
EventObject |
Um dos cinco tipos de resposta |
Solicitação: EventObject
Um EventObject
contém metadados de nível superior, campos de eventos comuns e detalhes contextuais
do aplicativo host:
Contexto comum e de autorização
commonEventObject: localidade do usuário, tipo enumerado do aplicativo hospedado (GMAIL,CALENDAR,DRIVE,CHAT,DOCS,SHEETS,SLIDES,WORKFLOW), plataforma do usuário, fuso horário, valores de entrada do formulário do widget (formInputs) e parâmetros personalizados. ConsulteCommonEventObject.authorizationEventObject: tokens de acesso OAuth do usuário, tokens de ID do usuário e escopos autorizados pelo sistema. ConsulteAuthorizationEventObject.
Objetos de evento do aplicativo host
Dependendo de qual aplicativo invoca o callback, um dos seguintes objetos host está presente:
- Gmail: ID da mensagem, ID da conversa, token de acesso temporário e listas de destinatários da mensagem (
toRecipients,ccRecipients,bccRecipients). ConsulteGmailEventObject. - Agenda: ID do evento, ID do evento recorrente, ID da agenda,
informações do organizador, convidados, dados da videoconferência e pontos de entrada. Consulte
CalendarEventObject. - Drive: arquivos ou pastas selecionados (
selectedItems) e metadados do item atual do cursor (activeCursorItem). ConsulteDriveEventObject. - Chat: tipo de evento (
ADDED_TO_SPACE,REMOVED_FROM_SPACE,MESSAGE,CARD_CLICKED), metadados do espaço, detalhes do usuário e dados do payload. ConsulteChatEventObject. - Workspace Studio: invocações de ações, eventos de ciclo de vida de gatilhos, configurações de elementos, recuperações de recursos e mapeamentos de dados de variáveis.
Consulte
WorkflowEventObject. - Documentos: ID do documento, título, flag de permissão do escopo do arquivo e padrão do URL correspondente. Consulte
DocsEventObject. - Planilhas: ID da planilha, título, flag de permissão de escopo de arquivo e padrão do URL correspondente. Consulte
SheetsEventObject. - Slides: ID da apresentação, título, flag de permissão de escopo de arquivo e padrão do URL correspondente. Consulte
SlidesEventObject.
Resposta: HandleEventResponse
A resposta HTTP retornada pelo endpoint do webhook é um objeto JSON raiz sem tag que precisa ser uma instância de um dos cinco tipos de resposta a seguir:
RenderActions: renderiza novos cards, navega por pilhas de cards ou executa ações de interface (por exemplo,{"action": {"navigations": [...]}}ou{"renderActions": ...}).SubmitFormResponse: responde a uma ação de envio de formulário do usuário com instruções de renderização de card e um indicador opcional de atualização de estado (por exemplo,{"renderActions": {...}, "stateChanged": true}).GetAutocompletionResponse: fornece sugestões de texto dinâmicas para campos de preenchimento automático de widgets (por exemplo,{"autoComplete": {"items": [...]}}).DataActions: realiza mutações de documentos ou ações de espaço do Chat acionadas pelo callback (por exemplo,{"hostAppDataAction": {...}}).AuthorizationError: solicita que o usuário autorize credenciais de terceiros ou solicita outros escopos do OAuth do Google (por exemplo,{"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).
Especificação independente da OpenAPI 3.0 e esquemas JSON
Para gerar automaticamente stubs de servidor, bibliotecas de cliente do SDK ou esquemas de validação de payload para seu endpoint de callback, consulte os seguintes arquivos de especificação:
- Especificação OpenAPI 3.0.3:
addon_callback_openapi.json - Definições de esquema JSON:
endpoint_interface.schema.json- Solicitar fragmento de esquema:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject - Fragmento do esquema de resposta:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse
- Solicitar fragmento de esquema: