How to Send Webhooks to Google Sheets with FastHook

FastHook supports Google Sheets as a first-class destination type:

GOOGLE_SHEET

Do not treat it as an HTTP destination, and do not add spelling aliases such as
GOOGLE_SHEETS, GOOGLESHEET, or typo-based normalization. The database
constraint, API contract, dashboard UI, and workers should use the exact
GOOGLE_SHEET value.

Backend Contract

Supported destination types are:

HTTP | CLI | MOCK_API | GOOGLE_SHEET

For GOOGLE_SHEET, the destination config is sheet-specific and does not
require config.url or config.path.

Required config:

• spreadsheet_id
• auth_type
• auth

Supported auth types:

• GOOGLE_OAUTH_REFRESH_TOKEN
• GOOGLE_SERVICE_ACCOUNT

OAuth config:

• auth.client_id
• auth.client_secret
• auth.refresh_token

Service account config:

• auth.client_email
• auth.private_key

When using a service account, the target spreadsheet must be shared with
auth.client_email.

Sheet Targeting

Use:

• sheet_name, default Sheet1
• range, default <sheet_name>!A:Z

The dashboard must not ask users to type range. It should derive the value
from sheet_name and save <sheet_name>!A:Z. API callers may omit range;
the backend normalizes it from sheet_name.

Simple Unicode sheet names do not need quotes, so Лист1 should become
Лист1!A:Z. When the sheet name contains spaces or A1 notation punctuation,
quote the sheet name:

'Orders Archive'!A:Z

Row Layout

Google Sheet delivery writes delivered events through the Google Sheets
values.append API.

Row layout rules:

• If columns is set, write those dotted payload/metadata paths in that exact order.
• If columns is empty and include_metadata is true, write FastHook metadata columns plus a payload snapshot.
• If columns is empty and include_metadata is false, auto-flatten the payload and spread payload values across columns.

Supported metadata paths include:

• delivered_at
• event_id
• request_id
• connection_id
• event_data_id
• team_id
• source_id
• destination_id

Payload paths can be written with or without the payload. prefix:

payload.customer.email
customer.email

Dashboard UI Rules

The dashboard should expose one destination editor shared by the Destinations
page and the Connections/Flow editor.

For Google Sheet destinations:

• Show Spreadsheet ID, Sheet name, Payload fields, Value input, Include metadata, and Google auth.
• Do not show Range; build it automatically from Sheet name as <sheet_name>!A:Z.
• Support both OAuth2 login and Service account.
• Hide the insert mode selector. The UI should save insert_data_option as INSERT_ROWS.
• Keep Max delivery rate enabled for Google Sheet destinations. Google Sheets API write quota is 60 requests/minute per user/project, so fix the UI at 1/second to avoid burst writes.
• Payload fields disables Include metadata, because explicit fields define the row layout.
• Include metadata disables Value input, because metadata rows should be written as RAW.
• If Include metadata is disabled and Payload fields is empty, payload data is auto-spread across columns.
• Keep Max delivery rate as the shared destination rate-limit control: enabled toggle, numeric value, and second | minute | hour.

Operational Notes

• Google Sheets API must be enabled in the Google Cloud project used by the OAuth client or service account.
• Google Sheets API write quota is 300 requests/minute per project and 60 requests/minute per user/project. Treat one Google Sheet destination as a single user/account quota and default rate limiting to 1/second.
• OAuth2 login requires the dashboard OAuth token exchange route and the public Google client id to be configured.
• After changing a destination config in production, clear the destination config cache if the send worker reads cached destination records.
• A failed Google Sheets delivery should be debugged from the event/attempt status first, then by checking auth, spreadsheet sharing, sheet name, and payload field mapping.