Ringkasan layanan
Saat pengguna memicu interaksi di aplikasi host yang didukung
(Gmail, Google Kalender, Google Drive,
Google Chat, Google Dokumen, Google Spreadsheet,
Google Slide, atau Workspace Studio), host akan mengirimkan
payload peristiwa POST HTTP ke URL callback add-on yang Anda konfigurasi (/*).
Endpoint add-on Anda harus menerima payload permintaan
EventObject
dan menampilkan salah satu dari lima jenis respons JSON yang valid yang didokumentasikan
dalam Respons: HandleEventResponse.
Kontrak endpoint webhook
| Metode | Jalur endpoint | Isi permintaan | Isi respons |
|---|---|---|---|
POST |
/* (atau jalur callback yang dikonfigurasi) |
EventObject |
Salah satu dari 5 jenis respons |
Permintaan: EventObject
EventObject
berisi metadata tingkat teratas, kolom peristiwa umum, dan detail kontekstual
aplikasi host:
Konteks umum dan otorisasi
commonEventObject: Lokalitas pengguna, enum aplikasi host (GMAIL,CALENDAR,DRIVE,CHAT,DOCS,SHEETS,SLIDES,WORKFLOW), platform pengguna, zona waktu, nilai input formulir widget (formInputs), dan parameter kustom. LihatCommonEventObject.authorizationEventObject: Token akses OAuth pengguna, token ID pengguna, dan cakupan yang diizinkan sistem. LihatAuthorizationEventObject.
Objek peristiwa aplikasi host
Bergantung pada aplikasi yang memanggil callback, salah satu objek host berikut akan ada:
- Gmail: ID pesan, ID rangkaian pesan, token akses sementara, dan daftar penerima pesan (
toRecipients,ccRecipients,bccRecipients). LihatGmailEventObject. - Kalender: ID acara, ID acara rutin, ID kalender,
informasi penyelenggara, tamu, data konferensi, dan titik entri. Lihat
CalendarEventObject. - Drive: File atau folder yang dipilih (
selectedItems) dan metadata item kursor saat ini (activeCursorItem). LihatDriveEventObject. - Chat: Jenis peristiwa (
ADDED_TO_SPACE,REMOVED_FROM_SPACE,MESSAGE,CARD_CLICKED), metadata ruang, detail pengguna, dan data payload. LihatChatEventObject. - Workspace Studio: Pemanggilan tindakan, peristiwa siklus proses pemicu, konfigurasi elemen, pengambilan resource, dan peta data variabel.
Lihat
WorkflowEventObject. - Dokumen: ID dokumen, judul, tanda izin cakupan file, dan
pola URL yang cocok. Lihat
DocsEventObject. - Spreadsheet: ID spreadsheet, judul, tanda izin cakupan file,
dan pola URL yang cocok. Lihat
SheetsEventObject. - Slide: ID presentasi, judul, tanda izin cakupan file,
dan pola URL yang cocok. Lihat
SlidesEventObject.
Respons: HandleEventResponse
Respons HTTP yang ditampilkan oleh endpoint webhook Anda adalah objek JSON root tanpa tag yang harus berupa instance salah satu dari lima jenis respons berikut:
RenderActions: Merender kartu baru, menavigasi tumpukan kartu, atau menjalankan tindakan UI (misalnya,{"action": {"navigations": [...]}}atau{"renderActions": ...}).SubmitFormResponse: Merespons tindakan pengiriman formulir pengguna dengan petunjuk render kartu dan indikator update status opsional (misalnya,{"renderActions": {...}, "stateChanged": true}).GetAutocompletionResponse: Memberikan saran teks dinamis untuk kolom pelengkapan otomatis widget (misalnya,{"autoComplete": {"items": [...]}}).DataActions: Melakukan mutasi dokumen atau tindakan ruang Chat yang dipicu oleh callback (misalnya,{"hostAppDataAction": {...}}).AuthorizationError: Meminta pengguna untuk mengizinkan kredensial pihak ketiga eksternal atau meminta cakupan Google OAuth tambahan (misalnya,{"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).
Spesifikasi OpenAPI 3.0 dan Skema JSON mandiri
Untuk membuat stub server, library klien SDK, atau skema validasi payload secara otomatis untuk endpoint callback Anda, lihat file spesifikasi berikut:
- Spesifikasi OpenAPI 3.0.3:
addon_callback_openapi.json - Definisi Skema JSON:
endpoint_interface.schema.json- Fragmen skema permintaan:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject - Fragmen skema respons:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse
- Fragmen skema permintaan: