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

Zendesk is a customer service solution that comes with everything you need to provide your customers with exceptional support.

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: B+
Event Catalog: A
Retry Policy: A-
Troubleshooting and Failure Recovery: B
Testing Tools: B+

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.

Zendesk offers the option for their users to create an HMACSHA256 signature for their webhooks and they offer a NodeJS code sample that demonstrates how to verify the signature.

One callout is that the code sample compares signatures using the buffer.compare() method which is not a constant time operation. Using a variable time comparison function is not recommended as it is vulnerable to timing attacks (see our article on how to securely verify signatures).

Grade: B+

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.

Zendesk has a full event catalog with all events. They first show the basic schema in common between all events with a specific example, and have a separate page where they outline the details specific to each event type with sample payloads for each.

Grade: A

Retry Policy

Zendesk's implementation of retries is fairly unique. We normally see a set number of retries that are offered when certain error codes are returned in the response. Zendesk offers 3 retries when receiving a 409 error code but 5 retries when webhooks timeout. It's not completely clear what the retry schedule is, but it is stated that users can set a retry-after header to specify when a retry should occur (up to 60s) so perhaps this is mostly configurable.

Zendesk also has a “webhook circuit breaker” feature that determines whether a webhook endpoint will stop receiving webhooks. This makes sure that users' endpoints don't get overwhelmed by failures and retries and pile up. This is the most detailed explanation of how a service determines when to disable endpoints we've seen and it's very appreciated.

Grade: A-

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.

Zendesk doesn't have a section on common failures or how to troubleshoot them, but they have a section on how to monitor webhooks. There is an endpoint to retrieve a log of webhook activity that also lets you filter by the message status so it's fairly simple to find all the failed messages which is a great place to start when troubleshooting failures.

Grade: B

Testing Tools

Zendesk doesn't have a section in the docs about testing but we did find a support article that mentions the ability to send test events. This is a huge quality of life boost when testing an endpoint implementation compared to having to find ways to trigger real events.

One thing Zendesk is missing that we see in many webhook docs is some instructions on how to use a tool like Svix Play to easily spin up an endpoint to receive test messages and inspect the incoming webhooks. This lets users start receiving webhooks without needing to deploy their own endpoint and helps increase adoption.

Another common inclusion is instructions on how to test webhooks in a local development environment. It's very common to suggest using a tool like ngrok or the Svix CLI that establish a public URL that tunnels requests to localhost.

Grade: B+

Summary

Overall, we were impressed with Zendesk's webhook documentation. It does a great job of getting users started with receiving webhooks and helping them follow best practices. The event catalog was extremely thorough and the “webhook circuit breaker” explanation in the retry section was also very well written.

Our three main suggestions for improvement are to add sections that help users test and troubleshoot their webhook endpoints and to use a constant time comparison function in the signature verification sample code.

---

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.