DEV Community: Andrew Lencmanis

How to Send Webhooks to Google Sheets with FastHook

Andrew Lencmanis — Wed, 08 Jul 2026 15:07:32 +0000

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.

Building a Replay-Safe Webhook Event Gateway

Andrew Lencmanis — Sun, 10 May 2026 19:35:23 +0000

Webhooks look simple at first: receive an HTTP request, forward it somewhere, return 200 OK.

That simplicity disappears the moment the system becomes production-critical. Providers retry. Consumers fail. Payloads arrive twice. Teams need to debug what happened yesterday. A single endpoint becomes dozens of integrations, each with its own routing, retry, transformation, and observability needs.

At that point, webhooks stop being “just HTTP callbacks” and become an event gateway problem.

This is the layer FastHook is built around: receive webhook requests, route them through connections, deliver events to destinations, and make every step inspectable and retryable.

The Core Model
A useful webhook gateway needs clear internal concepts.

In FastHook, a source is where inbound webhooks arrive. It represents the public endpoint that providers send requests to.

A destination is where routed events are delivered. For example, an internal API endpoint, a worker, or another HTTP service.

A connection links one source to one destination. This is where delivery behavior lives: filtering, transformation, retry, delay, and deduplication rules.

A request is the inbound webhook received by FastHook. It contains the original payload and request metadata.

An event is the outbound delivery created from an accepted request and a matching connection. Events can be queued, processed, delivered, failed, or ignored.

That separation matters. If a provider sends one webhook request and it matches several routing paths in the future, you want to inspect the original request separately from each delivery attempt. Even with one source-to-destination connection, keeping request and event separate makes retries, debugging, and metrics much cleaner.

Why Replay Safety Matters
Retries are not optional in webhook systems. They are the normal path.

A destination can return 500. A network request can timeout. A deploy can briefly break an endpoint. If the only recovery path is “ask the provider to resend it,” your system is fragile.

A replay-safe gateway stores enough information to retry later without losing context.

FastHook exposes this at two levels:

curl -X POST \
  "https://api.fasthook.io/v1/requests/req_.../retry" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-team-id: tm_..."

Request retry replays an inbound request through routing again.

curl -X POST \
  "https://api.fasthook.io/v1/events/evt_.../retry" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-team-id: tm_..."

Event retry retries a specific delivery event.

Those two operations solve different problems. If routing or connection rules changed, retrying the request can create fresh routed events. If only one destination delivery failed, retrying the event is more precise.

Bulk Retry Is Where Operations Become Real
Manual retry is useful. Bulk retry is where the system becomes operationally useful.

Imagine a destination was down for 30 minutes. You do not want to click retry 800 times. You want to filter failed events by time range, source, status, or search term, then create a controlled bulk operation.

For example:

curl -X POST \
  "https://api.fasthook.io/v1/events/bulk_operations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-team-id: tm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-04-17T00:00:00.000Z",
    "to": "2026-04-17T23:59:59.999Z",
    "status": "failed",
    "source_id": "src_...",
    "q": "stripe"
  }'

The important part is that replay is filtered and tracked as an operation, not treated as an invisible background action.

Observability Starts With Count APIs
Before retrying, teams usually ask: how many objects match this filter?

FastHook supports count endpoints for requests and events:

curl \
  "https://api.fasthook.io/v1/events/count?from=2026-04-17T00%3A00%3A00.000Z&to=2026-04-17T23%3A59%3A59.999Z&status=failed&source_id=src_..." \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-team-id: tm_..."

A typical response includes both the exact total and the applied time range:

{
  "total": 1234,
  "count": 1234,
  "total_exact": true,
  "applied_range": {
    "from": "2026-04-17T00:00:00.000Z",
    "to": "2026-04-17T23:59:59.999Z"
  }
}

That sounds small, but it changes the workflow. Operators can estimate blast radius before starting a replay.

Routing Rules Belong On Connections
Webhook providers usually send too much data to too few endpoints. A gateway needs routing rules between ingress and delivery.

FastHook connection rules can cover common operational needs:

filter rules decide whether a request should become an event for a connection.
transform rules modify payloads before delivery.
retry rules control retry behavior.
delay rules postpone delivery.
deduplicate rules help ignore duplicate deliveries inside a configured window.
This keeps source endpoints stable while letting each destination have its own behavior.

Transformations Need Their Own Audit Trail
Transformations are powerful, but they can also hide bugs. If a payload changes before delivery, teams need to know what ran and what came out.

A webhook gateway should treat transformation execution as inspectable data, not just inline code.

FastHook exposes transformation resources and execution history through the API, so teams can list transformations, run tests, and inspect executions tied to delivery behavior.

What To Avoid
The biggest mistake in webhook infrastructure is treating delivery as a single HTTP forward.

That loses the real story.

A production webhook gateway should not only answer “did we receive it?” It should answer:

Was the inbound request accepted or rejected?
Which connection matched it?
Which event was created?
Was the event delivered, failed, ignored, or retried?
What was the destination response?
Can we replay one event safely?
Can we bulk retry a filtered set?
Can we count the impact before doing it?
Once teams have those answers, webhook debugging stops being guesswork.

Closing
Webhooks are often the first integration surface a product exposes, but they are rarely treated as infrastructure until something breaks.

A replay-safe, observable event gateway gives teams a better foundation: stable source URLs, explicit routing, destination delivery tracking, retries, bulk operations, transformations, deduplication, and metrics.

That is the direction we are building with FastHook: not just receiving webhooks, but making webhook delivery understandable, recoverable, and safe to operate.

If you are building webhook infrastructure and want this as a managed product, FastHook is available at https://www.fasthook.io.