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 descriptions 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 its 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 its 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 its 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 . Svix makes it super easy to build a secure, reliable, and scalable webhook solution through an API. webhooks service For more content like this, make sure to follow us on , , or for the latest updates for the , or join the discussion on . Twitter GitHub RSS Svix webhook service our community Slack Also published here

The State of Webhooks in 2023

How to Receive Webhooks With Svix Bridge

Read My Stories

Too Long; Didn't Read

Make resilience your competitive advantage

Zoom Webhook Documentation Review: What It Does Well and What It Could Improve

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

Shhh...The Secret to Secrets Management: What You Need to Know

The Noonification: A Deep Dive Into Semantic Segmentation Evaluation Metrics (1/28/2024)

The Noonification: Pythons Testing Playbook: Building Bulletproof Code (1/21/2024)

11 Customer Feedback Software that Would Revolutionize 2022

11 Customer Support Response Templates That Will Improve Your Email Management

Shhh...The Secret to Secrets Management: What You Need to Know

The Noonification: A Deep Dive Into Semantic Segmentation Evaluation Metrics (1/28/2024)

The Noonification: Pythons Testing Playbook: Building Bulletproof Code (1/21/2024)

11 Customer Feedback Software that Would Revolutionize 2022

11 Customer Support Response Templates That Will Improve Your Email Management

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps