Webhook notifications
Last updated: Sep-19-2023
Cloudinary provides a webhook notification feature for informing your backend about certain actions that have been completed, either via API method call or via user action within the Console UI. When the action is completed, an HTTP POST request is sent to a public notification URL you provide. The payload contains all the results pertinent to that particular action.
You can use webhook notifications to:
- Handle asynchronous calls. By default, Cloudinary's upload API works synchronously. For example, uploaded assets are processed and eager transformations are generated synchronously during an upload API call, which means that the original asset and derived assets are available immediately for delivery and further management. However, in some cases you may need to be notified that an upload has completed, or you may want to process actions asynchronously in the background, especially actions that require a relatively long time to process and require your users to actively wait for the processing to finish.
- Keep aligned when other users in the system make changes. It's important to listen for changes made in your system and update accordingly to make sure there aren't any inconsistencies. You can set up code that listens for notifications, and then uses the data to make automatic updates. For example, you can set up a webhook to receive notifications when assets are renamed, and then trigger a search and replace to update the asset name anywhere it exists.
-
Integrate Cloudinary with other platforms. If you're using Cloudinary assets from within a different platform, listen for changes being made to assets in Cloudinary in order to keep synced. For example, you can set up a structured metadata field to indicate whether assets should be published or unpublished. When you receive a notification within the other platform indicating that this metadata field was changed, trigger the appropriate action in your code.
For more information about how to integrate Cloudinary with another platform, see How to build your own integration.
-
Trigger another operation. If an action must follow a specific event, you can listen for that event and use it to trigger the action. For example, use the notification that an asset has been uploaded to trigger adding the asset to your catalog. ExampleThe Cloudinary Solutions team took advantage of this option to create an open-source library that can learn and then auto-tag faces with names using an Amazon Rekognition lambda function that's triggered by the notification when photos are uploaded to a dedicated 'training' folder in Cloudinary.
Global notification URLs
You can set one or more global notification URLs in the Webhook Notifications page of the Console Settings or programmatically using the triggers
method of the Admin API.
Once you've set up either a single or multiple notification URL(s), Cloudinary automatically sends responses to the appropriate URL address(es) any time a relevant action in the Console UI is performed or a call to a relevant Cloudinary API method is made.
If you're using a single notification URL, configure it to receive all notifications.
However, adding multiple notification URLs enables you to specify which destination receives notifications for each type of action. This level of control makes is easy to trigger flows or sync multiple parts of your ecosystem when integrating Cloudinary with other platforms. It also allows you to:
- Dedicate a separate notification URL to handle actions relevant to each of your workflows.
- Organize your destinations according to their purpose.
- Spread out the traffic among several endpoints to avoid performance issues.
Tips and considerations for adding multiple notification URLs
- Make sure you assign every notification type that you listen for in your code to at least one notification URL.
- You can optionally set one notification URL to receive all responses as backup.
- Each notification URL can handle several event types, and conversely the responses for a single notification type can be sent to several notification URLs.
Managing global notification URLs
Managing webhook notifications from the Console
To manage multiple notification URLs via the Cloudinary Console, go to the Webhook Notifications Settings page.
By default, when you add a new notification URL, the Default - All notifications option is set as the default type. If you're using a single notification URL, or want to use one of your notification URLs as backup for all events, keep that default behavior.
You can also (or alternatively) add different Notification URLs, and select the Console UI action and/or API method Notification types that you want to be notified about at each URL.
notification_type
key that's returned in the body of the notification response. Managing webhook notifications programmatically
To manage notification URLs programmatically, use the triggers method of the Admin API. A trigger pairs a single triggering event (event_type
) with a notification URL. When the specified event occurs, a response is sent to its corresponding notification URL.
For example, set up the https://mysite.example.com/my_notification_endpoint
URL to receive a notification whenever an upload
is completed:
- If you want a trigger to receive all notifications, set its
event_type
toall
. - The
event_type
values correspond with thenotification_type
key that's returned in the body of the notification response.
API method call notifications
When you call certain API methods, a response is sent to the notification URL you configured to listen for that action upon its completion.
For a full list of possible triggering actions see this table.
For some examples of notification responses from these types of actions, see the Notification response examples section.
Console UI notifications
When a user performs any of the following actions in the Console UI, a response will be sent to the notification URL you configured to listen for that action upon its completion.
- Uploading a new asset.
- Renaming the asset's public ID.
- Deleting an asset. Deleting a folder that contains assets will also trigger a delete notification for all individual assets in that folder. Note that deleting empty folders does not send a notification.
- Updating an asset's display name. (Relevant only for product environments using dynamic folder mode.)
- Moving an asset between folders.
- In fixed folder mode, moving an asset to another folder in the Media Library changes the
public_id
value, and thus triggers a rename notification. - In dynamic folder mode, moving an asset to another folder changes the
asset_folder
value, and triggers a move notification.
- In fixed folder mode, moving an asset to another folder in the Media Library changes the
- Adding, removing or updating the contextual metadata for an asset.
- Adding, removing or updating the structured metadata for an asset.
- Adding or removing a tag for an asset.
- Updating the access control setting for an asset.
- Creating a new folder.
- Deleting a folder.
For a full list of possible triggering actions see this table.
For some examples of notification responses from these types of operations, see the Notification response examples section.
Notification Payload
When an action that triggers a notification is completed, an HTTP POST request will be sent to the notification URL you provided. The post data will contain all the result details for the action that triggered it. The body of this POST request is essentially the same information as you get in response to a standard synchronous request.
Here's an example POST request sent by Cloudinary after an upload completes:
For additional examples of notification responses from various API calls, see notification response examples.
Notification URLs for specific API calls
In specific situations, you may want to notify your backend as soon as a method call is complete, for example when dealing with user initiated uploads from a browser or mobile device. You can tell Cloudinary to notify your application as soon as the method is complete by adding the notification_url
parameter to the method call and setting it to any valid HTTP or HTTPS URL.
The following upload API methods support the notification_url
parameter: upload, explicit, explode, generate_archive, sprite, multi and create_collage.
For example, to add a notification_url
to a specific upload call:
notification_url
parameter in addition to any of the global notification URLs set to handle the relevant Notification type.Eager transformation notifications
You can instruct Cloudinary to send a separate notification whenever a requested Eager transformation completes by adding the eager_notification_url
parameter to the method call and setting it to any valid HTTP or HTTPS webhook URL. Eager transformations should be set up to work asynchronously in the background after an upload completes by also including the eager_async
parameter (for more details, see Eager asynchronous transformations). This eager notification is in addition to any notification sent via the optional notification_url
parameter.
The following upload API methods support the eager_notification_url
parameter: upload and explicit.
For example, the following method will upload the sample.jpg
image and then eagerly generate two transformed images:
- Pad to a width and height of 300 pixels.
- Crop to a width of 160 pixels and a height of 100 pixels.
Furthermore, the transformations will be performed asynchronously after the image finishes uploading, with a callback URL to notify your application once the upload is complete, and a different callback URL to notify your application once the eager transformations are complete:
Notification combinations with eager
The following table shows the results of adding different notification parameters when also requesting eager transformations with and without, the eager_async
parameter.
Parameters | Result |
---|---|
eager andnotification_url
|
The upload method response and the notification_url are sent after BOTH the upload completes and the eager transformations have finished. |
eager andeager_notification_url
|
The upload method response and the eager_notification_url are sent after BOTH the upload completes and the eager transformations have finished. |
eager andeager_notification_url andeager_async
|
- The upload method response is sent after the upload completes and include a batch_id for tracking the eager job. - eager_notification_url is sent after the eager transformations have finished with a batch_id for tracking. |
eager andnotification_url andeager_notification_url
|
The upload method response and the notification_url are sent after BOTH the upload completes and the eager transformations have finished. The eager notification is ignored. |
eager andnotification_url andeager_notification_url andeager_async
|
- The upload method response and the notification_url are sent after the upload completes and include a batch_id for tracking the eager job.- eager_notification_url is sent after the eager transformations have finished with a batch_id for tracking. |
Eager notification response
When the eager transformations are completed, an HTTP POST request will be sent to the eager notification URL you provided with details about the requested eager transformations including the HTTP and HTTPS URLs for accessing the derived images. For example:
If the eager transformation is not generated for some reason then the notification response will include a status: failed and the reason, for example:
Verifying notification signatures
Cloudinary signs all notification responses that it sends to your provided notification_url
or eager_notification_url
endpoint, allowing you to validate that they were not sent by a third-party. The notification includes both an X-Cld-Signature
header and a X-Cld-Timestamp
header for validating the notification response.
When you provide a notification_url
or eager_notification_url
endpoint in a method request, or if you set a global notification_url
in the Console Settings, Cloudinary includes both an X-Cld-Signature
header and a X-Cld-Timestamp
header with the response sent to the specified notification endpoint.
Here's an example POST request header sent by Cloudinary:
The signature is a hexadecimal message digest (hash value) created with the SHA-1 or SHA-256 (Secure Hash Algorithm) cryptographic function.
signature_algorithm
SDK configuration parameter to sha256
. If you want to limit your account to allow only the SHA-256 digest for all your validations, submit a request.Use the Cloudinary SDK's verify_notification_signature
method to verify the signature in the notification, and how many seconds it is valid for.
Alternatively, you can manually compare the returned signature value in the header with the value of a signature generated on your server side as follows:
- Create a single string containing the entire response body
- Append the X-Cld-Timestamp value on the end of the string.
- Append your API secret to the end of the string. (See the note below).
- Create a hexadecimal message digest (hash value) of the string using an SHA function.
api_key
that requested the notification. This is important where you use multiple key/secret pairs with your product environment, as you need to verify the signature using the corresponding api_secret
.For example, if the response body is {public_id: 'sample'}
, the X-Cld-Timestamp is 1315060510
, and your API secret is abcd
:
- Parameters to sign:
{public_id: 'sample'}
1315060510
- In a single string:
{public_id: 'sample'}1315060510
- String including the API secret that is used to create the SHA-1 signature:
{public_id: 'sample'}1315060510abcd
- SHA-1 hexadecimal result:
25f7e91709c858b97d688ce8da799dedb290d9ef
PHP code example for validating the notification:
Notification response examples
This section provides several examples of notifcation responses to a variety of different API calls or Media Library operations. Keep in mind that this list is not comprehensive, and that the exact content of the response will depend on the options sent with the relevant API call or the exact operation performed in the Media Library.
notification_context
with information on the time the original request was triggered and the source of that request - either an email address for a UI initiated request, or the api_key of an API method call.Tags
Context
Metadata
Rename
(Change the public ID)
Change display name
Supported only for product environments using dynamic folder mode.
Create folder
Move between asset folders
Supported only for product environments using dynamic folder mode.
Delete
Sprite generation
Multi generation
Explode
Create collage
Upload (simple)
Upload (complex)
Access control
Retry policy
In the event of a failed notification URL, the HTTP response code is assessed. If the response is not 200 OK
, three additional notification attempts are initiated:
- A retry after 3 minutes.
- A second attempt after 6 minutes.
- A final retry after 9 minutes.