How to Archive Webhooks to Google Cloud Storage (GCS)

When a webhook drives something important — a payment, an order, a deploy — you eventually want a record of exactly what the provider sent, not just whether your handler succeeded. An archive in Google Cloud Storage gives you that: an auditable, replayable history of every payload, ready to load into BigQuery. Webhook Relay Service Connections write webhooks to GCS for you, with no code.

How it works

Webhook Relay has service connections (your cloud credentials) and outputs (where to send data). Attach a GCS output to a bucket, and every webhook that arrives is stored as an object:

Provider --> Webhook Relay bucket --> GCS output --> gs://your-bucket/...

This runs alongside your normal delivery — you can forward the webhook to your app and archive it to GCS at the same time.

1. Create a GCP service connection

Add a service connection for GCP using a service account whose key can write objects to your bucket (the roles/storage.objectCreator role is enough). Webhook Relay encrypts secrets at rest (AES-256-GCM) and never returns them in full. See the GCS service connection docs for the exact steps.

2. Attach a GCS output

Add a GCS output to the bucket that receives your webhooks:

• Bucket name (required).
• Prefix (optional) — e.g. stripe/.
• Format — json (full webhook with headers, the default), body_only (raw body), or har.

Objects are written under a dated key so they're easy to browse and lifecycle:

{prefix}/{year}/{month}/{day}/{log_id}.json

3. Point your provider at the bucket URL

Use the bucket's public Webhook Relay endpoint as the webhook URL in your provider, then test:

curl -X POST https://your-webhook-relay-endpoint \
  -H 'Content-Type: application/json' \
  -d '{"event":"invoice.paid","id":"in_123"}'

An object appears in GCS within seconds.

Why archive webhooks

• Audit & compliance. Keep an immutable record of what each provider sent, with retention via object lifecycle rules.
• Debug after the fact. Inspect the exact payload that caused a problem, even days later.
• Replay. Re-feed stored payloads into a new service or a rebuilt handler.
• Load into BigQuery. Point an external table or a load job at the archive for analytics.

Going further

• Forward to your app and archive at once with multiple destinations.
• Transform or filter before storing.
• Stream straight into a warehouse with webhooks to BigQuery, or use S3 on AWS.

Inspect a webhook first or create a free account to set up the GCS archive.