Azure Blob Storage

This guide explains how to use Uploadcare as an upload and processing layer while storing files in your own Azure Blob Storage container. This is not a native integration — Uploadcare does not write to Azure directly. Instead, your backend listens for webhook events, downloads the file from Uploadcare, and uploads it to Azure Blob Storage using your Storage Account credentials.

Azure Blob Storage organizes files across three levels: a Storage Account holds one or more containers, and each container holds blobs. This guide uses “container” and “blob” consistently to match Azure’s terminology.

This pattern suits teams that:

• Run workloads on Azure and want to keep files within the same subscription and region as the rest of their infrastructure.
• Need to comply with data residency policies that require files to stay within specific Azure regions.
• Want to apply Uploadcare processing (resize, format conversion, etc.) before writing 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.
• An Azure subscription with a Storage Account created in the region closest to your users or backend. The region is fixed at Storage Account creation and cannot be changed.
• A container inside that Storage Account, created in the Azure Portal.
• A connection string for the Storage Account, available in the Azure Portal under your Storage Account settings. For production workloads, see the note on DefaultAzureCredential in Step 3.
• 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 your Azure Blob Storage container.
4. The file is deleted from Uploadcare or left to expire automatically.

Once the transfer is complete, your Azure container 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 keep files in Uploadcare only as long as necessary, disable autostore for the upload. Non-stored files expire automatically after a retention period, giving your backend time to complete the transfer before the file is removed.

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 Azure Blob Storage.

Step 3: Transfer the file to Azure Blob Storage

Azure Blob Storage provides an official client library for interacting with containers and blobs. Examples use Node.js — refer to the Azure Blob Storage SDK documentation for other languages.

$
npm install @azure/storage-blob

Initialize the client using your Storage Account connection string. The connection string encodes both the account name and key, so treat it as a secret — store it in an environment variable and never commit it to source control:

1
import { BlobServiceClient } from '@azure/storage-blob'
2
3
const blobServiceClient = BlobServiceClient.fromConnectionString(
4
  process.env.AZURE_STORAGE_CONNECTION_STRING
5
)

For production deployments running inside Azure (App Service, Azure Functions, AKS), use DefaultAzureCredential from @azure/identity instead. It authenticates via managed identity or service principal without any secret in your environment, which eliminates credential rotation overhead and reduces the risk of accidental exposure:

$
npm install @azure/storage-blob @azure/identity

1
import { BlobServiceClient } from '@azure/storage-blob'
2
import { DefaultAzureCredential } from '@azure/identity'
3
4
const blobServiceClient = new BlobServiceClient(
5
  `https://${process.env.AZURE_STORAGE_ACCOUNT_NAME}.blob.core.windows.net`,
6
  new DefaultAzureCredential()
7
)

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

1
async function transferToAzure(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 so each blob path is unique regardless of filename,
11
  // and so you can reconstruct the path later using only the Uploadcare UUID.
12
  const blobName = `uploads/${uuid}/${filename}`
13
14
  const containerClient = blobServiceClient.getContainerClient(
15
    process.env.AZURE_STORAGE_CONTAINER_NAME
16
  )
17
  const blockBlobClient = containerClient.getBlockBlobClient(blobName)
18
19
  await blockBlobClient.uploadData(buffer, {
20
    blobHTTPHeaders: {
21
      blobContentType: mimeType,
22
    },
23
  })
24
25
  return blobName
26
}

Setting blobContentType ensures Azure serves the blob with the correct Content-Type header when it is accessed directly or through a CDN — without it, browsers may treat the file as application/octet-stream regardless of extension.

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 blobName = await transferToAzure(uuid, original_file_url, filename, mime_type)
17
    console.log(`Transferred ${uuid} to Azure as: ${blobName}`)
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 tells Uploadcare the delivery failed and triggers automatic retries. This covers transient faults — brief Azure Storage unavailability, network timeouts on large files — without requiring a separate retry queue 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

Deleting the file right after a successful transfer closes the window during which it is accessible via Uploadcare’s CDN and prevents it from counting against your Uploadcare storage quota:

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 transferToAzure 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 for strict control over how long files remain accessible via Uploadcare and to keep storage costs predictable. Choose Option B when you want the simplest possible backend and the expiration window comfortably covers your transfer time.

Important considerations

Autostore behavior

Uploadcare projects have autostore enabled by default, so files are retained indefinitely unless explicitly deleted. To rely on 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 the same event may arrive more than once. The uploadData call above is safe to repeat — uploading to the same blob name overwrites the existing blob without returning an error. If your handler also writes to a database, guard those writes with a check on the UUID to avoid creating duplicate records.

Blob naming

The example uses uploads/{uuid}/{filename} as the blob name. The UUID prefix guarantees uniqueness within the container even when multiple users upload files with identical names, and it gives you a predictable path you can reconstruct from Uploadcare metadata at any point. You can adjust the prefix to fit your access patterns — for instance, organizing by date (uploads/2024/01/{uuid}/{filename}) simplifies Azure Blob lifecycle management policies, which let you automatically tier or delete blobs based on age.

Feature availability after file deletion

Uploadcare’s CDN delivery, URL API image transformations, and adaptive bitrate streaming 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 — Azure CDN, Azure Front Door, or Shared Access Signatures for private containers — before removing files from Uploadcare.

Summary

This flow lets you use Uploadcare as an upload and processing layer while keeping files in Azure Blob Storage. Uploadcare handles ingestion and emits a webhook; your backend authenticates to a Storage Account, downloads the file, writes it to a container as a block blob, 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 Google Cloud Storage, see Google Cloud Storage. For Amazon S3, see Direct uploads to S3 and Copy files to S3.