Cloudinary Webhooks Documentation Review

This post is a part of our "Documentation Review" series, where we collaborate with different companies to review, analyze and improve their docs. You can find the rest of the posts in the series here.

As the webhook as a service provider to companies like Brex, Benchling, and Lob, we obsess over our documentation and have read a lot of webhook documentation.

Cloudinary is an API platform for managing the entire image and video lifecycle from uploading to storage to optimizing to delivery. Thanks to Sharon Yelenik for collaborating with me on this review.

The best documentation we've seen generally has these five elements: (1) signature verification, (2) event catalog, (3) retry policy, (4) troubleshooting and failure recovery, and (5) testing tools.

TL;DR:
Signature Verification: A+
Event Catalog: A
Retry Policy: B+
Troubleshooting and Failure Recovery: A
Testing Tools: N/A

Signature Verification

Signature Verification is a critical security feature of webhooks. It lets users verify that a webhook was actually sent from the expected source. The signature verification section of webhook documentation should explain the signature scheme (how the signature is created) and give instructions on how to verify the signature with code samples.

Cloudinary does an amazing job with their signature verification. They start out with a quick explanation of why users should verify webhook signatures. They follow up with a sample header and sample code of how to use their SDK's verify_notification_signature function. They even explain how to manually verify the signature for those who don't want to use the SDK.

They also provide an extended code example in PHP that shows how to also check the timestamp values to guard against replay attacks.

Bravo!

Grade: A+

Event Catalog

The Event Catalog documents the event types users can subscribe to. They denote the type of message being sent and are the primary way for webhook consumers to configure what events they are interested in receiving. The best event catalogs list every available event type with sample payload schemas and description of what actions trigger the event.

Cloudinary provides many notification response examples for various notification types. There is also a link to a full event type table with a description of the event and the source method.

Grade: A

Retry Policy

Retries help make webhook systems more reliable. Endpoints can fail intermittently so retrying failed messages automatically avoids users losing important notifications.

Cloudinary retries their webhooks 3 times, in 3 minute intervals if a webhook returns a response with a status code other than 200. We generally recommend using an exponential backoff algorithm for retry timing because it addresses intermittent failures quickly while also giving users more time to fix a persistent issue.

Grade: B+

Troubleshooting and Failure Recovery

Describing a few of the most common failure modes can save users time and effort when troubleshooting a failing endpoint. You also want to provide instructions on how to re-enable an endpoint once the issue is resolved.

Cloudinary highlights payload corruption, an invalid signature, a disabled access key, an invalid URL, and connection timeouts as common causes of webhook failures. They also offer some advice on how to avoid these issues and have a note that they currently do not disable failing endpoints.

Grade: A

Testing Tools

The main improvement we would recommend is to give users guidance and options for testing their webhook implementations. We know that there are features to help users test their webhooks currently in development and would love to see them in action. A couple suggestions:

The ability to send test messages. It's a much better developer experience to get a sample message sent to your new endpoint instead of needing to figure out how to trigger an actual event.

A test endpoint generator like Svix Play. These tools let users start testing webhooks very quickly, without needing to develop their own endpoint. We mostly see people simply link to a 3rd party tool.

Grade: N/A

Summary

Cloudinary's webhook documentation is world class.

They do an amazing job of explaining how to verify their webhook signatures which is generally the biggest hurdle users face. They make it super easy to do with a signature verification function available in an SDK which is something we see very rarely.

The main area for improvement is helping users with testing, and there are plans for exploring new features and solutions. We'll be sure to check them out as they progress, and when they're ready, we'll update this review.

---

For more content like this, make sure to follow us on Twitter, Github or RSS for the latest updates for the Svix webhook service, or join the discussion on our community Slack.