Zoom Webhook 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.

We power the webhooks for many customers across a variety of industries, which means we get to see a lot of different webhooks docs. The documentation we've seen generally has these five elements: signature verification, event catalog, retry policy, troubleshooting and failure recovery, and testing tools.

Today, we're taking a look at Zoom's webhook docs. Zoom is a widely-used cloud-based video conferencing platform that facilitates virtual meetings, webinars, and online presentations.

TL;DR:
Signature Verification: A
Event Catalog: A
Retry Policy: B+
Troubleshooting and Failure Recovery: B
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.

This is one of the best sections of Zoom's webhook docs. They outline how the signature is generated with links to detailed explanations and provide sample code in Node.js. They've even prepared a github repo with a sample app as an implementation example.

To get an A+, we'd love to see them offer their users an SDK to make verifying webhooks even easier (e.g. Svix's open source SDKs).

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.

There is an extensive list of available event types with payload examples here: Zoom Event Catalog.

The only suggestion we would have is to mention and link to the event catalog directly (e.g. “You can find the full event catalog here”). Currently there is only a broken link to the user.created event type.

Grade: A

Retry Policy

Webhook messages can be prone to failures. Without retries, users may miss many notifications which results in a bad user experience. It's critical to fully describe the retry policy so users aren't surprised if something goes wrong. When are failed messages retried? When are they not retried? What is the maximum number of retries?

Zoom fully describes their retry policy including the number of retries (3), the retry schedule, and the conditions under which retries will and won't be attempted.

We would give a higher grade if there were a few more retry attempts. Currently, the first retry isn't attempted for a full 5 minutes which is a large delay in the case of a one off failure. The last retry before the endpoint is disabled is only 90 minutes after the first failure. Generally we'd like to see at least a 24 hour period to give developers time to receive a notification, diagnose the issue and implement a solution.

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.

Zoom has a good explanation of their endpoint validation and revalidation system so users know how to get their app back online. One thing we don't see is whether it's possible for users to recover messages that should have been sent while the endpoint was failing.

Here is an example from our receiving webhooks documentation:

https://docs.svix.com/receiving/using-app-portal/replaying-messages

Grade: B

Testing Tools

The main improvement we would recommend is to give users guidance and options for testing webhooks. The main features we see helping our users are the ability to send test messages as well as to generate an endpoint URL to receive those messages.

Summary

Overall, Zoom's webhook documentation is very detailed and does a great job explaining to their users how to set up webhook notifications.

We recommend that Zoom provide tools for testing and troubleshooting to improve the developer experience.

If you're looking to implement world class webhooks, consider trying Svix, the enterprise ready webhooks service. Svix makes it super easy to build a secure, reliable, and scalable webhook solution through an API.

---

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.