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

Razorpay is an online payment gateway that lets users accept payments from customers and automate payouts to vendors and employees.

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

Razorpay's signature verification section is packed with useful hints and tips to help users avoid common issues. Here are a few that we found very useful:

1. Use the raw webhook request body when calculating the signature.
2. The hash signature is calculated using HMAC with SHA256 algorithm; with your webhook secret set as the key and the webhook request body as the message.
3. Sample code for payloads that are QR Codes.

Massive points for offering a validate webhook function in an SDK. This makes webhook consumers' lives so much easier as verifying webhooks manually is one of the most common sources for errors when setting up a webhook receiver.

We would suggest organizing this section a bit differently. It's currently very easy to skip past the sample code which is super valuable for showing users how to use the SDK to massively simplify webhook signature verification. We think simply moving the code sample above the “Handy Tips” and callouts would help tie the mention of the SDK to the actual usage example. There are probably too many callouts in general (4 in a row if the code sample is moved). If you mark everything as a callout, nothing is a callout so we'd try to take a few of the callouts and just include them as regular text and save the callouts for the most important things users NEED to pay attention to.

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.

Razorpay has a section called “Sample Payloads” which is actually much more. Not only do they have sample payloads for every webhook event type, there are descriptions of each event type. There are even callouts that mention common issues you might run into when processing a specific event type.

The only suggestion we would have is to rename this section to “Event Catalog” as “Sample Payloads” makes it seem like all you'll see are payloads for a subset of the events.

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.

Razorpay retries their webhooks in an exponential backoff schedule over 24 hours. It's not explicitly stated how many retries are offered. There are multiple locations that mention “the exponential backoff schedule” but we couldn't find anywhere that outlined the actual schedule. This can be very helpful for developers to understand when subsequent retries will be attempted while they're debugging a failing endpoint.

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.

Most troubleshooting tips are spread throughout the docs in the form of tips and callouts. There is also an FAQ section that consolidates most of this advice in one place.

Grade: A

Testing Tools

There are three common ways that webhook docs suggest for testing webhooks and Razorpay has all three. The most common is linking to a request interceptor tool like Svix Play that spins up a public endpoint URL that you can send webhooks to and examine the payload and headers. This helps users try out the webhooks very quickly and without needing to build their own server to receive the webhook.

Second, is the ability to send test events. Razorpay offers a test mode to trigger test events. This is helpful both for initial setup and when troubleshooting/debugging an failing endpoint.

Last, how to test webhooks on localhost. To test a webhook, the endpoint URL needs to be public, so how can you test when you're still building locally? The answer is to use a tunnel. Most webhook docs do what Razorpay does which is to suggest using ngrok. It's the most popular tool for this use case. Alternatively, some products have their own CLI tool.

Grade: A+

Summary

Overall, Razorpay's webhook docs are great. Very detailed and comprehensive, they have every element of what is essential for users to have a great webhook experience.

The signature verification, event catalog, and testing sections were particularly thorough and helpful. The only suggestion we have would be to include the actual exponential backoff retry schedule in the docs so that users know how long they have to address a failing endpoint before they exhaust the retry schedule.

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.