Cloudinary Blog

A Blueprint for AWS-Secured Webhook Listeners for Cloudinary

A Blueprint for AWS-Secured Webhook Listeners for Cloudinary

tl;dr: An AWS-secured and optimized Cloudinary webhook listener for extending the Cloudinary service

Code: Github

A webhook is a communication medium for sending notifications from one platform to another about events that occurred. In place are user-defined HTTP callbacks that are triggered by specific events. When a triggered event takes place on the source site, the webhook listens to the event, collects the data, and sends it to the URL you specified in the form of an HTTP request.

With Cloudinary webhooks, you can augment Cloudinary capabilities with home-grown code or third-party APIs by triggering actions in your application when certain events occur in your Cloudinary account. In essence, a Cloudinary webhook is a small piece of code that takes action upon a Cloudinary event, such as a file upload, a metadata modification, or the complete processing of a media asset.

The sections below describe a blueprint of a Hello World! Cloudinary webhook listener that is deploy-ready and customizable with a few clicks or lines of code.

Real-Life Use Case

A prominent digital-transformation agency that specializes in luxury fashion migrated a legacy DAM to Cloudinary to leverage our platform’s new capabilities but continue to use the current middleware. Here’s what the agency aimed to accomplish:

Accordingly, the agency did the following:

  1. Adopted the template in this post to quickly deploy a global web listener that checks if an asset or the nominated metadata has been changed and, if so, update another metadata field to reflect the last update timestamp (last_update_timestamp).

  2. Fulfilled the polling requirement with Cloudinary’s search API.

  3. Through the same web listener, determined if an event is an upload of a video. If so, gauge if the video size is large or small.

  4. Executed the required preprocessing with Cloudinary’s explicit method.

Vincenzo Cerbone, technical consultant of openmind, said:

“We had a previous experience in batch synchronization with a legacy DAM based on polling techniques. Despite the pros and cons of that approach, we valued the user's asset state on Cloudinary the most. That means that we let the CMS act more as a ‘slave’ of the user's decisions on the Cloudinary side rather than the opposite. The connection point between the two worlds is the mandatory CMS_ID SMD custom field. The rest of the ‘magic’ is done through AWS Lambda functions (WebListeners) Yuval suggested. Ultimately, that mechanism took care of all the essential transformations.

We look forward to other upcoming features from Cloudinary that this use case can take advantage of. It’s truly exciting to be part of this process!”

Use Cases

Cloudinary offers an end-to-end media-management solution for images and videos, including upload, storage, administration, transformation, optimization, and delivery. The many features open up numerous use cases for a webhook listener, such as the following:

  • Updates to an activity feed on a front-end system with asset-related events and details, such as when someone uploads an asset to the Cloudinary Media Library or deletes one from there.
  • Bulk processing of records listed in an uploaded CSV file.
  • Updates to the asset metadata stored in an external database in the event of updates to an asset’s metadata in the Cloudinary Media Library
  • Extraction of metadata from assets uploaded with Cloudinary’s upload widget—for tagging in an external system.
  • Dispatch of a text message or email to a customer in case of asset uploads.

Overview Diagram


To create a blueprint for a Cloudinary webhook listener, you need the following:

Installation and Setup

Upon installation, the blueprint for a Cloudinary webhook listener calls for the following:

  1. Install a Lambda listener that adds the tag Hello World! to any asset you upload to your Cloudinary account.
  2. Store your Cloudinary account’s credentials in the Amazon Web Services (AWS) Secrets Manager, logging the web-listener activity in Cloudwatch.

The installation and setup process takes a few minutes. The boilerplate code is under 50 lines of Python script, easily accessible through AWS Lambda’s code editor.

To set up the tutorial, follow the instructions in the file.

Code Tutorial

  1. Write to your preferred logging solution: either use the default AWS logger with CloudWatch or override set_logger. The entry point is where the Cloudinary event was first received.

    validate_signature ensures that the events received are authentic. Note the mandatory return syntax, which informs Cloudinary that the function has been completed successfully. If the function fails, Cloudinary resends the notification three more times: once after three minutes, then after nine minutes, and then after 27 minutes. exception_wrapper adheres to that syntax as well.

  2. Place your code in the main_process function. The example below shows how to write back a tag to the uploaded asset. Here, to avoid additional I/O operations, the utility function config_cloudinary_instance() validates the event's authenticity with cached credentials.

Copy to clipboard
def lambda_handler(event, context):
    except Exception as e:
        return exception_wrapper(logger, e)
    return {'statusCode': 200, 'body': 'OK', 'isBase64Encoded': False}

The main_process function is where you’ll place your own code. The example shows how to write back a tag to the uploaded asset. To prevent additional I/O operations, the utility function config_cloudinary_instance() ensures that the cached credentials that validated the event's authenticity are in use.

Further Options and Resources

Check out the resources below on creating and managing webhook listeners.

When uploading assets:

When delivering assets:


As always, our goal at Cloudinary is to efficiently manage, transform, and optimize your web and mobile app's media assets, freeing you up to focus on your core business logic. Oftentimes, real-world use cases are complex and diverse, involving front-end and back-end systems as well as asynchronous workflows. Cloudinary’s webhooks with their ability to perform custom computing tasks promise to be useful tools for handling even the most demanding media-management tasks.

We’d much appreciate your feedback on this new blueprint.

Recent Blog Posts

The Pros and Cons of AVIF for Websites

AVIF is a 2019 spinoff from the AV1 video format developed by the Alliance for Open Media (AOM), whose members include Amazon, Apple, ARM, Facebook, Google, Huawei, Mozilla, Microsoft, Netflix, and Intel. As an open-source and royalty-free video codec, AVIF delivers much higher compression rates than the older image codecs like JPEG and WebP, and is on par with the brand-new JPEG-XL format, which does not work on any browser yet.

Read more
Get Your Media Moving Faster with Cloudinary’s Media Optimizer

So, your boss comes to you in a panic: he's just heard about Google's Core Web Vitals initiative and needs you to optimize the company website right now! "No problem," you say, hiding your fear that it's not something that can be done overnight. Just taking the first metric, Largest Contentful Paint (LCP), how can you possibly identify all the large elements - most likely images or video posters - of the many hundreds of pages that make up your site? There are already thousands of high-resolution (read massive) media files stored away, which marketing could use any time. How are you going to make sure they're all compressed to a size small enough to be delivered within the threshold? Not to mention all the new images and videos that will be created over time...

Read more
How to Tap Into the Value of User-Generated Content (UGC)

User-generated content (UGC) took off with, first of all, the advent of the internet and, subsequently, social networks. Everyday consumers were given keys to the kingdom, so to speak, so that they, too, could compose and post content, simultaneously engaging with others online. Twitter, Facebook, Instagram, Snapchat, TikTok—the networks through which we can create and publish content have grown exponentially, and brands are becoming aware of the benefits of tapping into the gold mines offered by those networks.

Read more
Identifying Countries by IP Address in Columnar Databases Through SQL

Cloudinary reaps a myriad of open web traffic, from ad networks to e-commerce sites. Our Data Science team is dedicated to analyzing the data for use internally and externally.

A glance at any General Data Protection Regulation (GDPR) article would reveal that—unlike Android device IDs (AID), through which users can reset their web address—keeping user identifiers, such as Internal Protocol (IP) and Media Access Control (MAC) addresses, as well as International Mobile Equipment Identity (IMEI), violates privacy. As a solution, you can discard all privacy identifications or make them visible to users for reset.

Read more
Digital-First Asset Management Explained

As the world changes, so does technology. I don’t need to name more than a handful of antiquated technologies before you nod in agreement: floppy disks, Walkmans, phone booths, VHS tapes, each of which have been phased out or rendered useless by new solutions that meet the same need but much more effectively.

Read more