# Uploadcare Webhooks

Uploadcare, the file upload, storage and CDN service, sends a JSON `POST` to your endpoint when a
file is uploaded, updated, stored, deleted or flagged as infected. If the webhook has a
`signing_secret`, each request carries an `X-Uc-Signature` header you verify against the raw body.

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

## When to Use This Skill

* How do I receive Uploadcare webhooks?
* How do I verify the Uploadcare `X-Uc-Signature` header?
* How do I handle `file.uploaded`, `file.stored`, `file.infected` or `file.deleted` events?
* Why does my Uploadcare webhook signature verification fail (401)?
* How do I set a signing secret on an Uploadcare webhook?

## Verification (core)

Signature = `v1=` + lowercase hex of HMAC-SHA256(signing secret, raw request body). Only the body is
signed: no timestamp, id or other header.

```javascript
const crypto = require('crypto');

function verifyUploadcareSignature(rawBody, header, secret) {
  if (!secret || typeof header !== 'string') return false;
  let sig = header.trim();
  if (sig.toLowerCase().startsWith('v1=')) sig = sig.slice(3); // bare digest also accepted
  sig = sig.toLowerCase();
  if (!/^[0-9a-f]{64}$/.test(sig)) return false;                // validate before decoding
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest(); // rawBody: Buffer
  return crypto.timingSafeEqual(expected, Buffer.from(sig, 'hex'));
}
// header: req.headers['x-uc-signature']; secret: process.env.UPLOADCARE_WEBHOOK_SECRET

```

* Use the **raw body bytes** (`express.raw({ type: '*/*' })`, `await request.arrayBuffer()`,
  `await request.body()`). Never `JSON.parse`/`JSON.stringify` before verifying.
* The key is the secret's UTF-8 bytes as-is (not hex- or base64-decoded).
* Python: `hmac.compare_digest` on **bytes**, after checking the digest is exactly 64 hex chars.
* Missing header, malformed value or mismatch: return `401`. Handled: `200`. Invalid JSON after a
  valid signature: `400`.
* Uploadcare's own Python sample uses a substring test (`calculated in header`); don't copy it.
* Nothing time-based is signed, so there is no replay window to enforce. Dedupe with idempotency.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/uploadcare-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/uploadcare-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/uploadcare-webhooks/examples/fastapi/).

## Event Types

Dispatch on `hook.event` in the body. `hook` also holds webhook and project information, `data`
describes the file, and `file` is its CDN URL.

| Event | Sent When |
| --- | --- |
| `file.uploaded` | A new file is uploaded, or created by a processing operation |
| `file.info_updated` | A file's metadata or appdata changes |
| `file.deleted` | A file is removed |
| `file.stored` | A file is stored |
| `file.infected` | A virus is detected (to be deprecated in favor of `file.info_updated`) |

REST API v0.6 webhooks only send `file.uploaded`; v0.7 sends all five and adds `initiator`,
`appdata`, `content_info` and `metadata`.

## Environment Variables

```bash
UPLOADCARE_WEBHOOK_SECRET=your_signing_secret   # the signing_secret set on the webhook

```

## Local Development

Uploadcare can't reach `localhost`. Tunnel with the Hookdeck CLI (no account required):

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

```

Use the printed URL as the webhook's target URL in Uploadcare.

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/uploadcare-webhooks/references/overview.md) - What Uploadcare webhooks are, events, payload, retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/uploadcare-webhooks/references/setup.md) - Create the webhook and set its signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/uploadcare-webhooks/references/verification.md) - Signature details, gotchas, debugging 401s
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/uploadcare-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests