# Guide to Uploadcare Webhooks: Features and Best Practices

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

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `x-uc-signature` |
| Body | JSON |
| Event routing | Body field `hook.event` |

From Uploadcare's [webhooks documentation](https://uploadcare.com/docs/webhooks):

* 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

| Key | Type | Description |
| --- | --- | --- |
| `hook` | object | Webhook, event and project information; `hook.event` is the event name |
| `data` | object | The file the event is about |
| `file` | string | CDN URL of the file |
| `initiator` | object | v0.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:

```json
{
  "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](https://uploadcare.com/docs/api/rest/webhook/update-webhook):

```bash
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:

```bash
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

```javascript
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.

```javascript
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](/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](/webhooks/guides/why-implement-asynchronous-processing-webhooks) and the [idempotency guide](/webhooks/guides/implement-webhook-idempotency).

## 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](https://hookdeck.com) verifies Uploadcare requests, keeps the webhook active during your outages and retries delivery.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Uploadcare webhooks reliably in minutes.