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.

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.
   Important

   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

PHP code example for validating the notification:

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.