Google Cloud Storage

This guide explains how to use Uploadcare as an upload and processing layer while storing files in your own Google Cloud Storage (GCS) bucket. This is not a native integration — Uploadcare does not write to GCS directly. Instead, your backend listens for webhook events, downloads the file from Uploadcare, and writes it to GCS using a service account.

This pattern suits teams that:

• Run workloads on Google Cloud and want to keep files in a bucket within the same project or region.
• Require fine-grained access control through IAM roles and service accounts.
• Want to apply Uploadcare processing (resize, format conversion, etc.) before committing files to long-term storage.

Prerequisites

Before you start, make sure you have:

• An active Uploadcare account with a project and its public and secret API keys.
• A Google Cloud project with the Cloud Storage API enabled.
• A GCS bucket created in the region closest to your users or backend. The bucket location is set at creation time and cannot be changed.
• A service account with the roles/storage.objectUser IAM role granted on the bucket. This role allows the account to read, create, and overwrite objects without granting broader project-level permissions.
• A JSON key file for that service account, downloaded from IAM & Admin → Service Accounts → Keys in the Google Cloud Console.
• A publicly reachable backend server capable of receiving HTTPS POST requests from Uploadcare.

How it works

The flow is driven by Uploadcare webhooks:

1. A file is uploaded via the File Uploader or Upload API.
2. Uploadcare processes the file and emits a file.uploaded webhook event to your endpoint.
3. Your backend receives the event, downloads the file from Uploadcare using the URL in the payload, and writes it to GCS using the service account credentials.
4. The file is deleted from Uploadcare or left to expire automatically.

Once the transfer is complete, your GCS bucket is the authoritative location for the file.

Recommended flow

Step 1: Upload a file

Use the File Uploader for browser-based uploads or the Upload API for server-side or programmatic uploads. At this stage, Uploadcare handles ingestion, validation, and any transformations you have configured.

To avoid holding files in Uploadcare longer than necessary, disable autostore for the upload. Non-stored files expire automatically after a retention period, which gives your backend sufficient time to complete the transfer before the file disappears.

To disable autostore on a per-upload basis, pass UPLOADCARE_STORE=0 when using the Upload API, or set store: false in the File Uploader configuration. To disable it project-wide, go to Project settings → Storage in the Dashboard.

Step 2: Receive the webhook event

Configure a webhook in your Uploadcare Dashboard under Project settings → Webhooks. Set the event type to file.uploaded and provide the URL of your backend endpoint.

When a file is uploaded, Uploadcare sends a POST request with a JSON payload:

1
{
2
  "id": 24877,
3
  "file": {
4
    "uuid": "eb7830fa-c59d-4ebb-ba2f-29b7c452ce84",
5
    "original_file_url": "https://ucarecdn.com/eb7830fa-c59d-4ebb-ba2f-29b7c452ce84/DSCN4715.JPG",
6
    "is_stored": false,
7
    "mime_type": "image/jpeg",
8
    "filename": "DSCN4715.JPG",
9
    "size": 7096467
10
  }
11
}

Your endpoint should:

1. Validate the request using the webhook signature (see below).
2. Extract file.uuid, file.original_file_url, file.filename, and file.mime_type from the payload.
3. Proceed to transfer the file to GCS.

Step 3: Transfer the file to GCS

Google Cloud Storage provides an official client library for interacting with GCS buckets. Examples use Node.js — refer to the Google Cloud Storage client libraries for other languages.

$
npm install @google-cloud/storage

Initialize the client using your service account credentials. Rather than referencing a key file path — which introduces a filesystem dependency and complicates containerized deployments — parse the JSON key content from an environment variable at runtime:

1
import { Storage } from '@google-cloud/storage'
2
3
const storage = new Storage({
4
  credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_JSON),
5
})

If you prefer to reference the key file directly (for example, in local development), use keyFilename instead:

1
const storage = new Storage({
2
  keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS,
3
})

Implement the transfer function. The example below fetches the file from Uploadcare and writes it to GCS in a single call:

1
async function transferToGCS(uuid, fileUrl, filename, mimeType) {
2
  const response = await fetch(fileUrl)
3
4
  if (!response.ok) {
5
    throw new Error(`Failed to fetch file from Uploadcare: ${response.status}`)
6
  }
7
8
  const buffer = Buffer.from(await response.arrayBuffer())
9
10
  // Prefix with the UUID to prevent naming collisions between files that share
11
  // a filename and to keep object paths reconstructable from Uploadcare metadata.
12
  const objectName = `uploads/${uuid}/${filename}`
13
14
  await storage.bucket(process.env.GCS_BUCKET_NAME).file(objectName).save(buffer, {
15
    contentType: mimeType,
16
  })
17
18
  return objectName
19
}

Wire it into a minimal Express.js webhook handler:

1
import express from 'express'
2
3
const app = express()
4
app.use(express.json())
5
6
app.post('/webhooks/uploadcare', async (req, res) => {
7
  const { file } = req.body
8
9
  if (!file) {
10
    return res.status(400).json({ error: 'Missing file payload' })
11
  }
12
13
  const { uuid, original_file_url, filename, mime_type } = file
14
15
  try {
16
    const objectName = await transferToGCS(uuid, original_file_url, filename, mime_type)
17
    console.log(`Transferred ${uuid} to GCS as: ${objectName}`)
18
    // Respond 200 so Uploadcare does not retry this event.
19
    res.status(200).json({ ok: true })
20
  } catch (err) {
21
    console.error(`Transfer failed for ${uuid}:`, err)
22
    // A non-2xx response causes Uploadcare to retry the webhook automatically.
23
    res.status(500).json({ error: 'Transfer failed' })
24
  }
25
})
26
27
app.listen(3000)

Returning a non-2xx status signals a failure to Uploadcare, which will retry delivery. This means transient errors — a momentary GCS outage, a DNS hiccup, or a timeout on a large file — are retried without any additional queue infrastructure on your end.

Step 4: Handle file lifecycle

After a successful transfer, decide what to do with the original file in Uploadcare.

Option A — Delete immediately via REST API

Removing the file as soon as the transfer succeeds limits the window during which it is accessible from Uploadcare’s CDN and keeps your Uploadcare storage usage predictable:

1
async function deleteFromUploadcare(uuid) {
2
  const response = await fetch(`https://api.uploadcare.com/files/${uuid}/`, {
3
    method: 'DELETE',
4
    headers: {
5
      Authorization: `Uploadcare.Simple ${process.env.UPLOADCARE_PUBLIC_KEY}:${process.env.UPLOADCARE_SECRET_KEY}`,
6
      Accept: 'application/vnd.uploadcare-v0.7+json',
7
    },
8
  })
9
10
  if (!response.ok) {
11
    throw new Error(`Failed to delete file ${uuid}: ${response.status}`)
12
  }
13
}

Call deleteFromUploadcare(uuid) after a successful transferToGCS call in your webhook handler.

Option B — Rely on auto-expiration

If is_stored is false in the webhook payload, the file was uploaded without autostore and Uploadcare removes it automatically after a retention period. No explicit deletion call is needed provided your backend completes the transfer within that window.

Choose Option A when you need precise control over file retention and Uploadcare storage costs. Choose Option B when reducing backend complexity is the priority and the expiration window fits your use case.

Important considerations

Autostore behavior

Uploadcare projects have autostore enabled by default, meaning uploaded files are retained indefinitely unless deleted. To use auto-expiration (Option B), disable autostore at the project level or pass UPLOADCARE_STORE=0 via the Upload API per request. The setting is available under Project settings → Storage in the Dashboard.

Idempotency

Uploadcare retries webhook delivery when your endpoint returns a non-2xx response, so your handler may receive the same event more than once for the same file. The save() call above is safe to repeat — GCS silently overwrites the existing object at the same path. If you write associated records to a database, guard those writes with a check on the UUID to prevent duplicate entries.

GCS object naming

The example uses uploads/{uuid}/{filename} as the object name. The UUID prefix makes each path unique within the bucket regardless of what users name their files, and it lets you locate the GCS object later using only the Uploadcare UUID. You can adjust the prefix structure to suit your access patterns — for example, organizing by date (uploads/2024/01/{uuid}/{filename}) simplifies bucket-level lifecycle policies and makes cost breakdowns by period straightforward.

Feature availability after file deletion

Uploadcare’s CDN delivery, URL API image transformations, and adaptive bitrate streaming all require the file to be present in Uploadcare. Once the file is deleted or expires, URLs served via Uploadcare’s CDN for that file will return errors. Decide on your delivery strategy — GCS uniform public access, Cloud CDN, or signed URLs — before removing files from Uploadcare.

Summary

This flow lets you use Uploadcare as an upload and processing layer while keeping files in Google Cloud Storage. Uploadcare handles ingestion and emits a webhook; your backend authenticates using a service account, downloads the file, writes it to GCS, and manages the lifecycle from there. CDN delivery and URL API transformations are only available while the file remains in Uploadcare, so finalize your delivery strategy before deleting or expiring files on the Uploadcare side.

For teams using Cloudflare R2, see Cloudflare R2 storage. For Amazon S3, see Direct uploads to S3 and Copy files to S3.