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-Signatureheader? - How do I handle
file.uploaded,file.stored,file.infectedorfile.deletedevents? - 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()). NeverJSON.parse/JSON.stringifybefore verifying. - The key is the secret's UTF-8 bytes as-is (not hex- or base64-decoded).
- Python:
hmac.compare_digeston 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.
| 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
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
- references/overview.md - What Uploadcare webhooks are, events, payload, retries
- references/setup.md - Create the webhook and set its signing secret
- references/verification.md - Signature details, gotchas, debugging 401s
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests