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.