Gareth Wilson Gareth Wilson

Guide to Uploadcare Webhooks: Features and Best Practices

Published


Uploadcare handles file uploads, storage, image and video processing, and delivery over its CDN. Its webhooks tell your application when files in a project are uploaded, stored, deleted or changed by an add-on, so you can keep your own records in step and react when a malware scan or content moderation check finishes.

This guide covers Uploadcare's per-event subscriptions, the payload and its API versions, opt-in signing with X-Uc-Signature, and the 72-hour retry window that ends with the webhook being disabled.

What are Uploadcare webhooks?

An Uploadcare webhook is a subscription in a project: one event, one target URL, an API version and an optional signing secret. To receive several events at the same URL, add a subscription for each. A target URL must be unique for each project and event, but one URL can serve several events through separate subscriptions.

You can manage webhooks in the dashboard's Webhooks section, which Uploadcare recommends, or through the REST API's webhook endpoints. Each webhook also has a payload version, which decides the available events and the shape of data. v0.7 is current and is the only version the create endpoint accepts. Older v0.6 webhooks receive only file.uploaded.

Uploadcare webhook features

FeatureDetails
Signaturehex HMAC-SHA256
Signature headerx-uc-signature
BodyJSON
Event routingBody field hook.event

From Uploadcare's webhooks documentation:

  • Only a 2xx counts as success. Each attempt times out after one minute.
  • Retries run 1, 5, 10, 30 and 60 minutes after the first attempt, then once an hour within 72 hours.
  • If every attempt in that window fails, the webhook is disabled and the project owner gets an email. Reactivation is manual, in the dashboard or through the API.
  • The v0.7 initiator field says what caused an event.

Events and payloads

Route on hook.event.

| Event routing | Body field hook.event |

REST API v0.6 supports only file.uploaded.

Event Payload Structure

KeyTypeDescription
hookobjectWebhook, event and project information; hook.event is the event name
dataobjectThe file the event is about
filestringCDN URL of the file
initiatorobjectv0.7 only. type is addon, api or system, plus detail

v0.7 data also has appdata, content_info and metadata.

data follows the REST API's file object, which the docs elide in every example. file.info_updated also carries previous_values, the earlier state of appdata or metadata. A key in it with a null value means that data was just added rather than updated.

initiator looks like this for a file created by an add-on:

{
  "initiator": {
    "type": "addon",
    "detail": {
      "addon_name": "zencoder_convert_video",
      "request_id": ":request_id",
      "source_file_uuid": ":UUID"
    }
  }
}

type is addon, api for any other API request such as an upload, or system for platform actions such as an expired file being removed. request_id is null for system.

Setting up Uploadcare webhooks

Set a signing_secret on the Uploadcare webhook. Without one, deliveries are unsigned and fail verification.

  1. In the Uploadcare dashboard, open your project's Webhooks section and add a webhook.
  2. Enter your endpoint URL, for example https://example.com/webhooks/uploadcare.
  3. Enter a signing secret of up to 32 characters.
  4. Choose API version v0.7 and the event.
  5. Repeat for each other event you need, then store the secret as UPLOADCARE_SIGNING_SECRET. Using the same secret for every subscription to one URL keeps verification simple.

To set a secret on an existing webhook through the REST API, send signing_secret to the update endpoint:

curl -X PUT \
  -H "Accept: application/vnd.uploadcare-v0.7+json" \
  -H "Authorization: Uploadcare.Simple $YOUR_PUBLIC_KEY:$YOUR_SECRET_KEY" \
  -d "signing_secret=some-secret" \
  "https://api.uploadcare.com/webhooks/WEBHOOK_ID/"

To route through Hookdeck, create an Uploadcare source with the signing secret and use its URL as the target URL. If you leave signing off in Uploadcare, leave verification off on the source too, since there's no signature to check. For local development:

npx hookdeck-cli listen 3000 uploadcare --path /webhooks/uploadcare

Securing Uploadcare webhooks

With a signing secret set, X-Uc-Signature has the form v1=<hex>: the hex HMAC-SHA256 of the request body, keyed with the secret. Without one, Uploadcare sends no header.

Uploadcare's Python sample checks whether the computed value appears anywhere in the header (calculated in header). Strip v1= and compare the exact digest in constant time instead.

Node.js verification

const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-uc-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = signature.split(',').map((part) => part.trim())
    .filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

Uploadcare documents no event ID. A file is uploaded, stored or deleted once, so the event name and file UUID make a usable key for those. file.info_updated can repeat for the same file, so the handler writes the latest state instead of deduplicating.

const express = require('express');

const app = express();

app.post('/webhooks/uploadcare', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.UPLOADCARE_SIGNING_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  let payload;
  try {
    payload = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return res.sendStatus(400);

  const hook = payload.hook && typeof payload.hook === 'object' ? payload.hook : {};
  const data = payload.data && typeof payload.data === 'object' ? payload.data : {};
  if (typeof hook.event !== 'string' || typeof data.uuid !== 'string') return res.sendStatus(400);

  try {
    if (hook.event === 'file.info_updated') {
      await saveFileInfo(data.uuid, { appdata: data.appdata, metadata: data.metadata });
    } else {
      const key = `${hook.event}:${data.uuid}`;
      if (await alreadyHandled(key)) return res.sendStatus(200);
      await queue.add('uploadcare-file', {
        event: hook.event,
        uuid: data.uuid,
        cdnUrl: payload.file,
        initiator: payload.initiator,
      });
      await markHandled(key);
    }
  } catch {
    return res.sendStatus(503);
  }
  res.sendStatus(200);
});

saveFileInfo, queue, alreadyHandled and markHandled stand for your own storage and job queue. Check data.uuid against a real delivery, since the docs' examples leave out the file fields.

Hookdeck performs the same check when you use its Uploadcare source type. A request that doesn't match is still acknowledged with 200, then recorded as failed verification. Hookdeck doesn't add a freshness window, and Uploadcare's signature has no timestamp to check against.

Make Uploadcare webhooks production-ready. Hookdeck Event Gateway accepts each Uploadcare request straight away, so a long outage on your side can't get the webhook disabled, and keeps the events until your service is back.

Uploadcare webhook limitations and pain points

Webhooks are disabled after 72 hours of failures

The Problem: After an outage of about three days, events stop and someone has to switch the webhook back on.

Why It Happens: If every attempt within the 72-hour retry window fails, Uploadcare disables the webhook and emails the project owner. Reactivation is manual.

Workarounds:

  • Make sure the project owner's email reaches someone who will act on it.
  • After reactivating, compare your records with the REST API's file list.

How Hookdeck Can Help: Hookdeck answers Uploadcare with a 2xx on every request, so the webhook stays active, and retries your service on your schedule.

One event per subscription

The Problem: Covering all five events means five subscriptions, each with its own settings and secret.

Why It Happens: A webhook subscribes to a single event, and the target URL must be unique per project and event.

Workarounds:

  • Script subscriptions through the REST API so they stay consistent.
  • Use the same signing secret on each subscription to the same URL.

How Hookdeck Can Help: Point every subscription at one Hookdeck source and route by hook.event from there.

Signing is opt-in

The Problem: Webhooks created without a secret send unsigned requests.

Why It Happens: signing_secret is optional, and no X-Uc-Signature header is sent without it.

Workarounds:

  • Set a secret on every subscription, including old ones, through the dashboard or a PUT to the webhook.
  • Reject requests that have no header.

How Hookdeck Can Help: Hookdeck's Uploadcare source records unsigned requests as failed verification, so you can see which subscriptions still lack a secret.

Elided examples and no event ID

The Problem: You can't see a complete payload in the docs or deduplicate on an ID.

Why It Happens: The examples replace hook and file fields with placeholders, and no event ID is documented.

Workarounds:

  • Capture one delivery per event and API version you use.
  • Build keys from the event and file UUID, and make file.info_updated handling an upsert.

How Hookdeck Can Help: Hookdeck stores each full payload for you to inspect and replay.

Best practices

Use v0.7

v0.7 supports all five events and adds appdata, content_info, metadata and initiator. v0.6 sends only file.uploaded.

Move off file.infected

Uploadcare plans to deprecate file.infected in favour of file.info_updated. Read the malware scan result from appdata.uc_clamav_virus_scan instead.

Use initiator to avoid loops

If your own code converts files, initiator.type and detail.addon_name tell you which uploads came from your processing, so you don't process them again.

Respond within a minute

Queue the work and answer with a 2xx. See processing webhooks asynchronously and the idempotency guide.

Conclusion

Uploadcare sends one event per subscription, with hook.event naming it and data holding the file, signed with v1= plus a hex HMAC-SHA256 when you set a signing secret. Set the secret on every subscription, use v0.7, and respond with a 2xx within a minute, because 72 hours of failures disables the webhook.

Hookdeck Event Gateway verifies Uploadcare requests, keeps the webhook active during your outages and retries delivery.

Get started with Hookdeck for free and handle Uploadcare webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.