Agent skill

Uploadcare Webhooks Skill

Receive and verify Uploadcare webhooks. Use when setting up an Uploadcare webhook endpoint, verifying the X-Uc-Signature header (v1= HMAC-SHA256 of the raw body), debugging 401s, or handling file.uploaded, file.info_updated, file.deleted, file.stored and file.infected events.

Install this skill

npx skills add hookdeck/webhook-skills --skill 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.

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/, examples/nextjs/, 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.

EventSent When
file.uploadedA new file is uploaded, or created by a processing operation
file.info_updatedA file's metadata or appdata changes
file.deletedA file is removed
file.storedA file is stored
file.infectedA 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

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):

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

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

Resources


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →