Cloudinary integration

What it does

The Cloudinary integration lets your agency drive a client's media pipeline from inside a workflow. Connect a client's Cloudinary product environment once and your workflows can upload images, video and raw files, search the asset index, read and update asset metadata, manage tags, context and structured metadata, organise folders, generate archives, register named transformations, and read plan usage. Cloudinary notifications arrive as triggers, one per event type, and TaskJuice registers and tears down the notification URLs for you.

Connect a Cloudinary account

1. Open your workspace in TaskJuice, add a Cloudinary node to a workflow, and create the connection from the node.

2. In a new tab, open the Cloudinary console dashboard signed in as the client (or as your agency, if the client has delegated environment access to you).

3. Copy the Cloud name, API key, and API secret from the Product Environment Credentials panel.

4. Paste the cloud name into TaskJuice. It scopes every API call and is templated into the base URL https://api.cloudinary.com/v1_1/{cloud_name}.

   The cloud name is the short name that appears in a delivery URL — res.cloudinary.com/<cloud name>/…. It is not the 32-character Product Environment ID shown next to it. Pasting the environment ID fails every call with 401 cloud_name mismatch, which reads like a bad credential.

5. Paste the API key and API secret. Cloudinary sends them as HTTP Basic credentials (key as username, secret as password) on every request.

   If you plan to use Cloudinary triggers, the key you paste matters. Cloudinary signs webhook notifications with the secret of exactly one key in the product environment: the key designated dedicated_for: webhooks, or — when none is designated — the oldest active key. Every active key authenticates Admin and Upload calls identically, so pasting a newer scoped key produces a connection where all actions work, the notification URL registers successfully, and every delivery then fails signature verification with nothing on screen to explain it. Paste the signing key, or designate the key you want to use for webhooks first.

6. Add the connection at the account level if you want triggers. TaskJuice mirrors the API secret to the tenant-wide inbound verifier only from an account-scoped connection; a workspace-scoped connection leaves actions working and gives trigger deliveries no key to verify against.

To rotate credentials, regenerate the API secret in the Cloudinary console and then save the TaskJuice connection again. That secret is also what TaskJuice verifies webhook signatures with, so rotating it without re-saving leaves inbound deliveries failing verification.

Triggers

Cloudinary exposes 29 notification event types, and TaskJuice ships one trigger per type — asset lifecycle (New Asset Uploaded, Asset Deleted, Asset Renamed, Asset Moved, Asset Published), asynchronous processing (Eager Transformation Completed, Archive Generated, Sprite Generated, Animated Asset Created, Multi-page Asset Exploded, Asset Analysis Completed), metadata (Asset Tags Changed, Asset Context Metadata Changed, Asset Structured Metadata Changed, Asset Display Name Changed, Asset Access Control Changed), moderation and proofing, folders, and operational events such as Asset Operation Failed.

Publishing a workflow registers the notification URL with Cloudinary automatically through the Admin API — there is nothing to paste into the console.

Removing triggers is currently one-directional: registrations are added automatically, but deleting a trigger does not yet withdraw its registration from Cloudinary. Until that is fixed, remove unwanted notification triggers in the Cloudinary console (Settings → Webhooks) as well. This matters on Cloudinary specifically because the 30-notification-URL budget below is consumed by registrations no workflow references.

TaskJuice verifies every delivery against Cloudinary's own signature: sha1(body + X-Cld-Timestamp + api_secret), hex, in the X-Cld-Signature header. The API secret on the connection is the key, so there is no separate webhook secret to collect — provided that secret belongs to the key Cloudinary signs with (see step 5). If deliveries never arrive, this is the first thing to check: a mismatched key rejects every notification while leaving the rest of the integration healthy.

Actions

Upload and processing — upload-image (image, video, raw or auto), explicit-asset (eager transformations and re-moderation without re-uploading), rename-asset, generate-archive.

Reading assets — search-assets (Cloudinary search expressions, newest first, cursor-paginated), get-resource, get-asset-by-id, list-resources, list-assets-by-folder, list-assets-by-tag, list-assets-by-moderation.

Updating assets — update-asset (by public ID), update-asset-by-id (by the immutable asset ID, so the step survives renames and folder moves), manage-tags, update-context, update-structured-metadata, add-related-assets, remove-related-assets, restore-asset-version.

Deleting — delete-resource (by public ID), delete-assets-by-prefix, delete-assets-by-tag.

Folders — create-folder, list-folders, list-subfolders, rename-folder, delete-folder.

Transformations and operations — list-transformations, get-transformation, create-named-transformation, get-usage, list-tags, list-upload-presets.

Known limitations

• Per-account rate limits, transformation quotas, and feature entitlements are governed by the client's Cloudinary plan, not by TaskJuice. The Admin API allows 500 requests per hour on the Free plan. When Cloudinary returns a 420 or 429, the action surfaces as a retryable rate-limit error.
• Cloudinary allows 30 notification URLs per product environment, counted across event types. Each enabled trigger consumes one, so a single workspace can enable at most 30 of the 29 available triggers — and two TaskJuice workspaces pointing at the same Cloudinary environment share that budget.
• The connected cloud name is fixed on the connection. To work across two Cloudinary product environments, create a second connection. Note that webhook signature verification stores one signing secret per app per tenant, written from the account-scoped connection, so a second environment's account-scoped connection replaces the first one's — verify triggers for one Cloudinary environment per TaskJuice account.
• restore-asset-version requires backups to be enabled on the product environment. Without them Cloudinary answers 200 with a per-asset no_backup error rather than an HTTP error.
• update-structured-metadata only accepts metadata fields that already exist in the product environment's metadata schema; an unknown external ID is a 400.
• generate-archive always runs in Cloudinary's create mode and returns the stored archive asset. Cloudinary's download mode streams the ZIP bytes back instead of JSON, which has no workflow-usable output, so it is not exposed.
• Delivery-URL building is not an action. Compose transformation URLs from an asset's secure_url in an expression instead — Cloudinary has no endpoint for it, and calling one would cost a request for a pure string operation.