cloudinary-webhooks

Cloudinary Webhooks

Cloudinary sends webhook notifications to a URL you register, telling your app when assets are uploaded, eager transformations finish, moderation completes, assets are deleted or renamed, folders change, and more. Each POST is a JSON body signed with your account API Secret and delivered with two headers: x-cld-signature (a hex digest) and x-cld-timestamp (a unix timestamp).

When to Use This Skill

• How do I receive Cloudinary webhooks / notifications?
• How do I verify the x-cld-signature header on a Cloudinary webhook?
• Why is my Cloudinary webhook signature verification failing?
• How do I handle upload, eager, or moderation notifications?
• What are the Cloudinary notification_type values?

Verification (core)

Cloudinary signs the raw request body concatenated with the timestamp and your account API Secret. Verify with the official SDK — it enforces a freshness window (default 7200s) as well as the digest. Use the raw body byte-for-byte — do not JSON.parse then re-stringify before verifying.

const cloudinary = require('cloudinary').v2;
cloudinary.config({
  api_secret: process.env.CLOUDINARY_API_SECRET,
  signature_algorithm: process.env.CLOUDINARY_SIGNATURE_ALGORITHM || 'sha1', // 'sha256' if enabled
});

// rawBody = exact request body string; headers come from the request
const signature = req.get('x-cld-signature');
const timestamp = req.get('x-cld-timestamp');

// Reject missing headers with 400 first — a 401 should mean "bad signature".
if (!signature || !timestamp) return res.status(400).send('Missing signature headers');

// verifyNotificationSignature(body, timestamp, signature, valid_for = 7200) -> boolean
const valid = cloudinary.utils.verifyNotificationSignature(rawBody, Number(timestamp), signature);
if (!valid) return res.status(401).send('Invalid signature');

Cloudinary computes the signature as a plain hex digest of rawBody + timestamp + api_secret using sha1 (default) or sha256 (an opt-in account setting) — it is not a keyed HMAC, though Cloudinary's docs sometimes call it "HMAC-SHA1". The SDK abstracts this; see references/verification.md for the exact scheme and a manual fallback.