Cloudinary

You run the service on your own server. Cloudinary notifies it of each upload, and it stores the watermarked copy next to the original.

upload to Cloudinary ──notification──► your service ──► Etchv
       ▲                                                 │
       └──────── watermarked copy as <public_id>_etchv ◄─┘

The service is in the Etchv integrations repository under the MIT license.

What you get

• The original stays as it was. The copy is stored as <public_id>_etchv in the same asset folder and tagged etchv-watermarked.
• Etchv embeds {"public_id": "<source public ID>", "delivery": "<reference>"}. The copy's contextual metadata records etchv_watermark_id and etchv_source, so you can match a detected watermark to the upload it came from.
• Replacing the original watermarks the new version and replaces the copy. Deleting the original leaves the copy in place.
• Public image uploads in JPEG, PNG, TIFF, PSD/PSB, GIF, BMP, PPM and WebP are watermarked, up to 50 MB. Each one uses the same credits as an image embed.

Run the service

You need Node.js 24 (24.2 or later) and a host that can receive HTTPS requests from Cloudinary. The service serves plain HTTP, so put it behind your HTTPS proxy or platform.

Set these environment variables:

Then start it:

git clone https://github.com/etchv-labs/integrations.git
cd integrations
npm install
cd cloudinary
npm start

The service README lists the other optional variables, such as SHA-256 signatures, a regional Cloudinary API host or another suffix for the copy.

Keep both keys on the server. The service never logs them.

Connect Cloudinary

Point an upload notification at the service's HTTPS URL:

• For all uploads: in the Cloudinary Console, open Settings → Webhook Notifications and add a notification URL for the Upload event type. Keep the signature scheme at default or legacy HMAC and keep the default payload. The service verifies the X-Cld-Signature header, which the EdDSA-only scheme doesn't send.
• For some uploads: pass notification_url in the upload call, or set it on an upload preset. Global notifications that aren't additive then don't also fire for that upload.

Cloudinary signs notifications with the key chosen for signature verification on the same settings page, or your oldest active key if none is chosen. If that isn't the key in CLOUDINARY_API_KEY, set CLOUDINARY_WEBHOOK_SECRET to its secret. Otherwise every notification gets a 401.

To choose the delivery reference per upload, add a tag such as delivery:partner-42. Uploads without one use ETCHV_DELIVERY.

Upload an image, then look for <public_id>_etchv in the same folder. To confirm the watermark, detect it in the copy and compare the watermark ID with etchv_watermark_id.

Retries and failures

Cloudinary waits 20 seconds for a response, then retries after about 3, 6 and 9 minutes. Each version of an upload maps to one idempotency key, so a retry replays the same Etchv result instead of using more credits. The service keeps working after Cloudinary stops waiting, so run it where a request can continue for a few minutes.

After a 200 failure, fix the cause and upload the image again.