Programmable Media

Verifying notification signatures

Last updated: May-17-2024

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.

You can set a specific key as the dedicated API key for verifying all notifications programmatically via the PUT method of the Provisioning API access key endpoint, available for Enterprise customers upon request.

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.

By default, Cloudinary supports both SHA-1 and SHA-256 digests for validation, and you can use either. The SDK methods use the SHA-1 algorithm by default, but you can use the SHA-256 algorithm instead by setting the 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 Cloudinary SDKs to verify the signature

Use the Cloudinary SDK's verify_notification_signature method to verify the signature in the notification, and how many seconds it is valid for.

Manually verify the signature

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:

  1. Create a single string containing the entire response body
  2. Append the X-Cld-Timestamp value on the end of the string.
  3. Append your API secret to the end of the string.
    When dealing with multiple API keys in your product environment, it's essential to identify the appropriate key for verification. If you've established a dedicated API key for all your webhook notifications, make sure to employ the associated api_secret for verification. Otherwise, use the oldest active key in your product environment.
  4. Create a hexadecimal message digest (hash value) of the string using an SHA function.

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

You should also compare the timestamp value with the current time to make sure that the signature was generated within a reasonable amount of time (e.g., within the last 2 hours).

PHP code example for validating the notification:

See also
Have a look at the Cloudinary Signatures quick reference for a summary of the payload string to sign for notification signatures as well as information on other use cases that may require signature generation.

Dedicated API key for webhook notifications

If you're working with multiple API key/secret pairs in your product environment, you have the option to specify an API key that will serve as the dedicated key for verifying webhook notifications. The dedicated API key can be used for other purposes, as well.

The benefit of selecting a dedicated key is that it provides clarity, ensuring you always know which key to use for verification. If you don't set a dedicated API key, the system employs the oldest active key in your product environment for webhook verification.

To set the dedicated API key, navigate to the Webhook Notifications page of the Console Settings and click Select API Key.

Keep in mind that only one API key can be dedicated to webhook notifications. Therefore, selecting a new API key for this purpose will replace the previously designated key.

A dedicated API key can also be set programmatically via the PUT method of the Provisioning API access key endpoint, available for Enterprise customers upon request

✔️ Feedback sent!

Rate this page: